@libraz/libcantus 0.9.0 → 0.9.2

package/src/theory/scale/degrees.ts

@@ -0,0 +1,123 @@
+import type { KeyScale } from '../../core/types.js';
+
+/** Reduce a pitch (or pitch class) to a pitch class in [0, 11]. */
+function pitchClass(pitch: number): number {
+  return ((Math.trunc(pitch) % 12) + 12) % 12;
+}
+
+/** Scale offset of a pitch relative to the key root, in [0, 11]. */
+function scaleOffset(pitch: number, key: KeyScale): number {
+  return (pitchClass(pitch) - pitchClass(key.rootPc) + 12) % 12;
+}
+
+/**
+ * Test whether a pitch belongs to the scale.
+ *
+ * @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;
+}
+
+/**
+ * Find the nearest MIDI pitch whose pitch class is in the scale.
+ *
+ * The search expands symmetrically outward from `pitch`. On a tie (equal
+ * distance above and below) the lower pitch is returned.
+ *
+ * @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);
+  for (let distance = 0; distance < 12; distance += 1) {
+    const lower = base - distance;
+    if (isScaleTone(lower, key)) {
+      return lower;
+    }
+    const higher = base + distance;
+    if (isScaleTone(higher, key)) {
+      return higher;
+    }
+  }
+  return base;
+}
+
+/**
+ * Get the 0-based scale degree of a pitch.
+ *
+ * @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);
+  if (((key.modeMask12 >> offset) & 1) === 0) {
+    return -1;
+  }
+  let degree = 0;
+  for (let n = 0; n < offset; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      degree += 1;
+    }
+  }
+  return degree;
+}
+
+/**
+ * List the pitch classes of a key's scale.
+ *
+ * @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);
+  const pcs: number[] = [];
+  for (let n = 0; n < 12; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      pcs.push((root + n) % 12);
+    }
+  }
+  return pcs.sort((a, b) => a - b);
+}
+
+/**
+ * List the pitch classes of a key's scale in ascending scale-degree order.
+ *
+ * Degree 0 is the root; degrees follow the mask bits in offset order rather
+ * than sorted pitch-class order.
+ *
+ * @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);
+  const pcs: number[] = [];
+  for (let n = 0; n < 12; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      pcs.push((root + n) % 12);
+    }
+  }
+  return pcs;
+}

package/src/theory/scale/index.ts

@@ -0,0 +1,28 @@
+export {
+  diatonicPitchClasses,
+  isScaleTone,
+  nearestScaleTone,
+  pitchToScaleDegree,
+  scaleTonesInDegreeOrder,
+} from './degrees.js';
+export { majorKey, minorKey, scaleByName } from './key.js';
+export {
+  BLUES_MASK,
+  CHROMATIC_MASK,
+  DORIAN_MASK,
+  HARMONIC_MINOR_MASK,
+  LOCRIAN_MASK,
+  LYDIAN_MASK,
+  MAJOR_MASK,
+  MAJOR_PENTATONIC_MASK,
+  MELODIC_MINOR_MASK,
+  MINOR_PENTATONIC_MASK,
+  MIXOLYDIAN_MASK,
+  maskFromOffsets,
+  NAMED_SCALES,
+  NATURAL_MINOR_MASK,
+  OCTATONIC_HALF_WHOLE_MASK,
+  OCTATONIC_WHOLE_HALF_MASK,
+  PHRYGIAN_MASK,
+  WHOLE_TONE_MASK,
+} from './masks.js';

package/src/theory/scale/key.ts

@@ -0,0 +1,56 @@
+import type { KeyScale } from '../../core/types.js';
+import { MAJOR_MASK, NAMED_SCALES, NATURAL_MINOR_MASK } from './masks.js';
+
+/**
+ * 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.
+ *
+ * @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 };
+}
+
+/**
+ * Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
+ *
+ * @param name The scale name, e.g. `'dorian'` or `'harmonicMinor'`.
+ * @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];
+  if (mask === undefined) {
+    throw new Error(`Unknown scale: ${name}`);
+  }
+  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: mask };
+}

package/src/theory/scale/masks.ts

@@ -0,0 +1,153 @@
+/**
+ * Build a 12-bit mode mask from a list of semitone offsets above the root.
+ *
+ * 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;
+  for (const offset of offsets) {
+    mask |= 1 << (((offset % 12) + 12) % 12);
+  }
+  return mask;
+}
+
+/**
+ * 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}.
+ *
+ * @category Scales
+ */
+export const NATURAL_MINOR_MASK = 0b010110101101;
+
+/**
+ * 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}.
+ *
+ * @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}.
+ *
+ * @category Scales
+ */
+export const DORIAN_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 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}.
+ *
+ * @category Scales
+ */
+export const LYDIAN_MASK = maskFromOffsets([0, 2, 4, 6, 7, 9, 11]);
+
+/**
+ * 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}.
+ *
+ * @category Scales
+ */
+export const LOCRIAN_MASK = maskFromOffsets([0, 1, 3, 5, 6, 8, 10]);
+
+/**
+ * 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}.
+ *
+ * @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}.
+ *
+ * @category Scales
+ */
+export const BLUES_MASK = maskFromOffsets([0, 3, 5, 6, 7, 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}.
+ *
+ * @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}.
+ *
+ * @category Scales
+ */
+export const OCTATONIC_WHOLE_HALF_MASK = maskFromOffsets([0, 2, 3, 5, 6, 8, 9, 11]);
+
+/**
+ * Chromatic scale: all twelve pitch classes.
+ *
+ * @category Scales
+ */
+export const CHROMATIC_MASK = 0b111111111111;
+
+/**
+ * Named scale masks addressable by {@link scaleByName}.
+ *
+ * @category Scales
+ */
+export const NAMED_SCALES: Record<string, number> = {
+  major: MAJOR_MASK,
+  ionian: MAJOR_MASK,
+  naturalMinor: NATURAL_MINOR_MASK,
+  aeolian: NATURAL_MINOR_MASK,
+  harmonicMinor: HARMONIC_MINOR_MASK,
+  melodicMinor: MELODIC_MINOR_MASK,
+  dorian: DORIAN_MASK,
+  phrygian: PHRYGIAN_MASK,
+  lydian: LYDIAN_MASK,
+  mixolydian: MIXOLYDIAN_MASK,
+  locrian: LOCRIAN_MASK,
+  majorPentatonic: MAJOR_PENTATONIC_MASK,
+  minorPentatonic: MINOR_PENTATONIC_MASK,
+  blues: BLUES_MASK,
+  wholeTone: WHOLE_TONE_MASK,
+  octatonicHalfWhole: OCTATONIC_HALF_WHOLE_MASK,
+  octatonicWholeHalf: OCTATONIC_WHOLE_HALF_MASK,
+  chromatic: CHROMATIC_MASK,
+};

package/src/{spelling → theory/spelling}/index.ts

@@ -7,11 +7,11 @@
  * A harmonic minor spells its seventh as G#.
  */
 
+import type { Note } from '../../core/pitch/index.js';
+import { formatNote } from '../../core/pitch/index.js';
+import type { KeyScale } from '../../core/types.js';
 import type { Chord } from '../chord/index.js';
-import type { Note } from '../pitch/index.js';
-import { formatNote } from '../pitch/index.js';
 import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
 
 /** Semitone offset of each natural letter above C: C D E F G A B. */
 const LETTER_SEMITONES = [0, 2, 4, 5, 7, 9, 11] as const;
@@ -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 → theory/symbol}/index.ts

@@ -5,14 +5,24 @@
  * (`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';
 
-/** Matches a chord root: a letter A-G with an optional single-direction accidental. */
-const ROOT_RE = /^[A-G](?:#{1,2}|b{1,2})?/;
+import {
+  formatNote,
+  midiToNote,
+  type Note,
+  noteToPitchClass,
+  parseNote,
+} from '../../core/pitch/index.js';
+import { type Chord, type ChordQuality, makeChord, type PitchSpelling } from '../chord/index.js';
+
+/**
+ * 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 +124,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 +170,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 +212,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 +247,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/theory/voicing/index.ts

@@ -0,0 +1,5 @@
+export { nextVoicing, voiceLeadingCost } from './leading.js';
+export type { VoiceRange, VoicingOptions } from './satb.js';
+export { SATB_RANGES, voiceChord, voiceProgression } from './satb.js';
+export type { StyledVoicingOptions, VoicingStyle } from './styled.js';
+export { voiceChordStyled } from './styled.js';