@libraz/libcantus 0.9.0 → 0.9.1

package/src/model/index.ts

@@ -81,7 +81,14 @@ function copyNote(data: NoteData): NoteData {
   return copy;
 }
 
-/** Defensive copy of a plain chord. */
+/**
+ * Defensive copy of a plain chord.
+ *
+ * Any enharmonic spelling hints (`rootSpelling`/`bassSpelling`, populated by
+ * `parseChordSymbol`) are carried through so a flat-named chord round-trips
+ * through the class API; a hint that no longer matches its pitch class is
+ * simply ignored by the formatter.
+ */
 function copyChord(data: ChordData): ChordData {
   const copy: ChordData = {
     rootPc: data.rootPc,
@@ -91,6 +98,12 @@ function copyChord(data: ChordData): ChordData {
   if (data.bassPc !== undefined) {
     copy.bassPc = data.bassPc;
   }
+  if (data.rootSpelling !== undefined) {
+    copy.rootSpelling = { letter: data.rootSpelling.letter, alter: data.rootSpelling.alter };
+  }
+  if (data.bassSpelling !== undefined) {
+    copy.bassSpelling = { letter: data.bassSpelling.letter, alter: data.bassSpelling.alter };
+  }
   return copy;
 }
 
@@ -104,6 +117,13 @@ function spellPitchClassBare(pc: number, spelling: 'sharp' | 'flat'): NoteData {
  * 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'
+ * ```
  */
 export class Note {
   readonly #data: NoteData;
@@ -196,12 +216,16 @@ export 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.
    */
   transpose(semitones: number): Note {
+    if (semitones === 0) {
+      return new Note(this.#data);
+    }
     if (this.#data.octave !== undefined) {
       return Note.fromMidi(this.midi + semitones);
     }
@@ -231,12 +255,31 @@ export class Note {
       this.#data.octave === other.#data.octave
     );
   }
+
+  /**
+   * 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(): NoteData {
+    return this.data;
+  }
 }
 
 /**
  * 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'
+ * ```
  */
 export class Interval {
   readonly #number: number;
@@ -292,6 +335,18 @@ export class Interval {
   get name(): string {
     return `${this.#quality}${this.#number}`;
   }
+
+  /**
+   * 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 {
+    return { number: this.#number, quality: this.#quality, semitones: this.#semitones };
+  }
 }
 
 /** Resolve a string or numeric key root into a spelled tonic note. */
@@ -299,10 +354,38 @@ function resolveTonic(root: string | number, spelling: 'sharp' | 'flat'): Note {
   return typeof root === 'string' ? Note.of(root) : new Note(spellPitchClassBare(root, spelling));
 }
 
+/** Total accidentals a spelled tonic produces across a key's whole scale. */
+function accidentalLoad(tonic: NoteData, scale: KeyScale): number {
+  return spellScale(tonic, scale).reduce((sum, note) => sum + Math.abs(note.alter), 0);
+}
+
+/**
+ * Choose the tonic spelling (sharp- or flat-side) that spells `scale` with the
+ * fewest accidentals, so a numeric root never yields a double-flat/double-sharp
+ * scale (e.g. pitch class 6 minor spells as F# minor, not Gb minor with Bbb).
+ */
+function bestTonicForScale(rootPc: number, scale: KeyScale): Note {
+  const sharp = spellPitchClassBare(rootPc, 'sharp');
+  const flat = spellPitchClassBare(rootPc, 'flat');
+  if (sharp.letter === flat.letter && sharp.alter === flat.alter) {
+    return new Note(sharp);
+  }
+  return accidentalLoad(flat, scale) <= accidentalLoad(sharp, scale)
+    ? new Note(flat)
+    : new Note(sharp);
+}
+
 /**
  * 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)
+ * ```
  */
 export class Key {
   readonly #scale: KeyScale;
@@ -322,25 +405,35 @@ export 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 {
-    const tonic = resolveTonic(root, 'sharp');
-    return new Key(majorKey(tonic.pitchClass), tonic);
+    if (typeof root === 'string') {
+      const tonic = Note.of(root);
+      return new Key(majorKey(tonic.pitchClass), tonic);
+    }
+    const scale = majorKey(root);
+    return new Key(scale, bestTonicForScale(root, scale));
   }
 
   /**
    * 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 {
-    const tonic = resolveTonic(root, 'flat');
-    return new Key(minorKey(tonic.pitchClass), tonic);
+    if (typeof root === 'string') {
+      const tonic = Note.of(root);
+      return new Key(minorKey(tonic.pitchClass), tonic);
+    }
+    const scale = minorKey(root);
+    return new Key(scale, bestTonicForScale(root, scale));
   }
 
   /**
@@ -486,6 +579,20 @@ export class Key {
   contains(x: number | Note): boolean {
     return isScaleTone(typeof x === 'number' ? x : x.pitchClass, this.#scale);
   }
+
+  /**
+   * 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: NoteData } {
+    return { scale: this.scale, tonic: this.#tonic.data };
+  }
 }
 
 /**
@@ -493,6 +600,13 @@ export class Key {
  * 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)
+ * ```
  */
 export class Chord {
   readonly #data: ChordData;
@@ -712,7 +826,10 @@ export class Chord {
    * @throws If no key is given and none is carried.
    */
   negativeHarmony(key?: Key): Chord {
-    return new Chord(negativeHarmonyMirror(this.#data, this.#resolveKey(key).scale), this.#key);
+    const resolved = this.#resolveKey(key);
+    // Retain the key that anchored the reflection (explicit first, then carried)
+    // so a later no-arg analysis method still has a key context.
+    return new Chord(negativeHarmonyMirror(this.#data, resolved.scale), key ?? this.#key);
   }
 
   /**
@@ -720,6 +837,9 @@ export 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.
@@ -732,7 +852,11 @@ export class Chord {
     }
     const index = ((n % length) + length) % length;
     const data = copyChord(this.#data);
-    data.bassPc = mod12(this.#data.rootPc + (intervals[index] ?? 0));
+    if (index === 0) {
+      delete data.bassPc;
+    } else {
+      data.bassPc = mod12(this.#data.rootPc + (intervals[index] ?? 0));
+    }
     return new Chord(data, this.#key);
   }
 
@@ -835,6 +959,15 @@ export 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']
+ * ```
  */
 export class Progression {
   readonly #chords: readonly Chord[];
@@ -946,6 +1079,22 @@ export class Progression {
     return { chords, 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: ChordData[]; key: { scale: KeyScale; tonic: NoteData } | undefined } {
+    return {
+      chords: this.#chords.map((chord) => chord.data),
+      key: this.#key?.toJSON(),
+    };
+  }
+
   /** Resolve the key for an analysis method: explicit first, then carried. */
   #resolveKey(key?: Key): Key {
     const resolved = key ?? this.#key;

package/src/motif/index.ts

@@ -4,7 +4,11 @@ import { isScaleTone, nearestScaleTone } from '../scale/index.js';
 import type { ChordTimeline } from '../timeline/index.js';
 import type { KeyScale } from '../types.js';
 
-/** A transformation applicable to a motif cell. */
+/**
+ * A transformation applicable to a motif cell.
+ *
+ * @category Composition
+ */
 export type MotifTransform =
   | 'transposeDiatonic'
   | 'transposeChromatic'
@@ -14,27 +18,62 @@ export type MotifTransform =
   | 'diminish'
   | 'sequence';
 
-/** A single note within a motif cell. */
+/**
+ * A single note within a motif cell.
+ *
+ * @category Composition
+ */
 export type MotifNote = {
   pitch: number;
   startBeat: number;
   durationBeat: number;
 };
 
-/** A short melodic cell. */
+/**
+ * A short melodic cell.
+ *
+ * @category Composition
+ */
 export type MotifCell = {
   notes: MotifNote[];
 };
 
-/** Melodic contour shape for {@link generateMotif}. */
+/**
+ * Melodic contour shape for {@link generateMotif}.
+ *
+ * @category Composition
+ */
 export type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
 
-/** Options controlling {@link generateMotif}. */
+/**
+ * Options controlling {@link generateMotif}.
+ *
+ * @category Composition
+ */
 export type GenerateMotifOptions = {
   key: KeyScale;
   chord?: Chord | 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;
 };
 
@@ -126,7 +165,6 @@ function mulberry32(seed: number): () => number {
 /** Diatonic scale-degree offsets shaping a contour of `count` notes. */
 function contourOffsets(contour: MotifContour, count: number): number[] {
   const offsets: number[] = [];
-  const half = Math.floor(count / 2);
   for (let i = 0; i < count; i += 1) {
     switch (contour) {
       case 'ascending':
@@ -136,7 +174,9 @@ function contourOffsets(contour: MotifContour, count: number): number[] {
         offsets.push(-i);
         break;
       case 'arch':
-        offsets.push(i <= half ? i : count - 1 - i);
+        // Symmetric rise-and-fall: a palindrome that starts and ends on the
+        // tonic (offset 0) for both odd and even lengths.
+        offsets.push(Math.min(i, count - 1 - i));
         break;
       case 'wave':
         offsets.push([0, 1, 0, -1][i % 4] ?? 0);
@@ -151,10 +191,21 @@ function contourOffsets(contour: MotifContour, count: number): number[] {
  *
  * 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
  */
 export function generateMotif(opts: GenerateMotifOptions): MotifCell {
   const contour = opts.contour ?? 'arch';
@@ -163,12 +214,19 @@ export function generateMotif(opts: GenerateMotifOptions): MotifCell {
   const noteCount = Math.max(3, bars * 2);
   const beatsPerNote = totalBeats / noteCount;
   const rng = mulberry32(opts.seed ?? 0);
+  const jitterProb = Math.min(1, Math.max(0, opts.jitter ?? 0));
   const tonic = pitchClass(opts.key.rootPc) + 60;
   const offsets = contourOffsets(contour, noteCount);
 
   const notes: MotifNote[] = [];
   for (let i = 0; i < noteCount; i += 1) {
-    const jitter = rng() < 0.25 ? 1 : 0;
+    // Opt-in, direction-balanced jitter: disabled by default so the contour is
+    // preserved exactly. When enabled it nudges up or down with equal odds,
+    // avoiding the upward bias that used to drift arch/wave tails off the tonic.
+    let jitter = 0;
+    if (jitterProb > 0 && rng() < jitterProb) {
+      jitter = rng() < 0.5 ? 1 : -1;
+    }
     let pitch = stepDiatonic(tonic, (offsets[i] ?? 0) + jitter, opts.key);
     const startBeat = i * beatsPerNote;
     if (opts.chord && startBeat % 4 === 0) {
@@ -197,6 +255,15 @@ export 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
  */
 export function transformMotif(
   cell: MotifCell,
@@ -279,6 +346,16 @@ function scaleTime(cell: MotifCell, factor: number): MotifCell {
  * @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
  */
 export function developMotif(
   cell: MotifCell,

package/src/pitch/index.ts

@@ -24,6 +24,8 @@ const LETTER_NAMES = ['C', 'D', 'E', 'F', 'G', 'A', 'B'] as const;
  *   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
  */
 export type Note = {
   letter: number;
@@ -31,7 +33,11 @@ export type Note = {
   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
+ */
 export type SpelledInterval = {
   /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
   number: number;
@@ -62,6 +68,13 @@ function mod7(n: number): number {
  * @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
  */
 export function parseNote(text: string): Note {
   const match = /^([A-Ga-g])([#x]*|b*)(-?\d+)?$/.exec(text.trim());
@@ -103,6 +116,12 @@ function formatAlter(alter: number): string {
  *
  * @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
  */
 export function formatNote(note: Note): string {
   const glyph = LETTER_NAMES[mod7(note.letter)] ?? 'C';
@@ -115,6 +134,12 @@ export function formatNote(note: Note): string {
  *
  * @param note The note.
  * @returns The pitch class.
+ * @example
+ * ```ts
+ * import { noteToPitchClass, parseNote } from '@libraz/libcantus';
+ * noteToPitchClass(parseNote('Db')); // 1
+ * ```
+ * @category Pitch & Intervals
  */
 export function noteToPitchClass(note: Note): number {
   const natural = LETTER_SEMITONES[mod7(note.letter)] ?? 0;
@@ -127,6 +152,12 @@ export function noteToPitchClass(note: Note): 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
  */
 export function noteToMidi(note: Note): number {
   if (note.octave === undefined) {
@@ -170,9 +201,20 @@ const FLAT_SPELLING: readonly [number, 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
  */
 export function midiToNote(midi: number, spelling: 'sharp' | 'flat' = 'sharp'): Note {
   const rounded = Math.round(midi);
@@ -227,6 +269,13 @@ function diatonicIndex(note: Note): number {
  * @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
  */
 export function spelledInterval(a: Note, b: Note): SpelledInterval {
   const octaved = a.octave !== undefined && b.octave !== undefined;
@@ -240,11 +289,17 @@ export function spelledInterval(a: Note, b: Note): SpelledInterval {
     letterSteps = mod7(b.letter - a.letter);
     let rawSemis = mod12(noteToPitchClass(b) - noteToPitchClass(a));
     // Lift the chromatic span into the octave nearest the diatonic reference so
-    // wraparound intervals (e.g. Ab -> G# = augmented seventh) stay consistent
-    // with the ascending diatonic number instead of collapsing modulo 12.
+    // wraparound intervals stay consistent with the diatonic number instead of
+    // collapsing modulo 12. The correction is bidirectional: an upward wrap
+    // (e.g. Ab -> G# = augmented seventh) adds an octave, while a same-letter or
+    // downward chromatic step (e.g. E -> Eb, F# -> F, C -> Cb = descending
+    // diminished/augmented unison) subtracts one so the sign follows pitch
+    // direction instead of returning a garbage stack of augmentations.
     const reference = SIMPLE_REFERENCE[letterSteps + 1] ?? 0;
     if (reference - rawSemis > 6) {
       rawSemis += 12;
+    } else if (rawSemis - reference > 6) {
+      rawSemis -= 12;
     }
     semitones = rawSemis;
   }