@libraz/libcantus 0.9.2 → 0.9.3

package/dist/index.d.cts

@@ -1,14 +1,15 @@
-export { AnalyzedNote, ArrangementAnalysis, ArrangementOptions, ArrangementTrack, ChordMatch, Conflict, KeyMatch, TensionPoint, TheoryLabel, TrackAnalysis, TrackRole, VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, detectChord, detectChordBest, detectKey, romanToChord, tensionCurve } from './analyze/index.cjs';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from './function-r2sh-jOO.cjs';
-export { C as CadenceHit, a as ChordSegment, b as ChordTimeline, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from './index-D_ZTUNKp.cjs';
-export { IntervalQuality, JUST_RATIOS, Rng, TWELVE_TET, Tuning, centsBetweenFreq, centsOfSteps, classifyInterval, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents } from './core/index.cjs';
+export { AnalyzedNote, ArrangementAnalysis, ArrangementOptions, ArrangementTrack, Conflict, TensionPoint, TheoryLabel, TrackAnalysis, TrackRole, VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve } from './analyze/index.cjs';
+export { C as ChordMatch, D as DetectChordOptions, K as KeyMatch, d as detectChord, a as detectChordBest, b as detectKey } from './index-CnZCo29u.cjs';
+export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from './function-DYt4iKsn.cjs';
+export { C as CadenceHit, a as ChordSegment, b as ChordTimeline, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from './index-CpOsP1y9.cjs';
+export { DEFAULT_GENERATION_BUDGET, IndexedNoteEvent, IntervalQuality, JUST_RATIOS, NoteEventIndex, Rng, TWELVE_TET, Tuning, assertFiniteNumber, assertGenerationBudget, assertInteger, assertNoteEvent, assertNoteEvents, assertPositiveInt, assertRange, assertTimeSignature, centsBetweenFreq, centsOfSteps, classifyInterval, createNoteEventIndex, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents } from './core/index.cjs';
 export { B as BarPosition, T as TimeSignature, b as barPositionToBeat, a as beatToBarPosition, c as beatsPerBar, f as formatTimeSignature, i as isCompound, d as isStrongBeat, m as metricWeight, p as parseTimeSignature, e as pulsesPerBar, t as tuplet } from './index-Cl7mhOFM.cjs';
 export { N as NoteData, S as SpelledInterval, f as formatNote, m as midiToNote, n as noteToMidi, a as noteToPitchClass, p as parseNote, s as spelledInterval } from './index-CGMZNCx6.cjs';
 export { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.cjs';
 export { BassLineOptions, BassSegment, BassStyle, BorrowedChord, CounterMelodyOptions, DrumHit, DrumRole, DrumsOptions, EuclideanKick, GrooveFeel, GrooveSlot, GrooveStyle, GrooveTemplate, HarmonizeOptions, HarmonizeResult, HumanizeOptions, MelodyNote, MotifCell, MotifContour, MotifNote, MotifOptions, MotifTransform, ProgFunction, ProgStyle, ProgressionOptions, ProgressionPreset, RhythmEvent, RhythmOptions, Section, SubstituteOptions, Substitution, SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif } from './generate/index.cjs';
 export { Chord, Interval, Key, Note, Progression } from './model/index.cjs';
-export { C as ChordData, a as ChordQuality, b as ChordSpan, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from './index-BOBXBNwP.cjs';
-export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, d as VoicingOptions, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from './styled-BjXtOFNk.cjs';
+export { C as ChordData, a as ChordQuality, b as ChordSpan, P as PitchSpelling, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from './index-BNlGP86A.cjs';
+export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, d as VoicingOptions, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from './styled-ZTbdaVFM.cjs';
 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, NAMED_SCALES, NATURAL_MINOR_MASK, OCTATONIC_HALF_WHOLE_MASK, OCTATONIC_WHOLE_HALF_MASK, PHRYGIAN_MASK, WHOLE_TONE_MASK, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, formatChordSymbol, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, maskFromOffsets, minorKey, nearestScaleTone, nextVoicing, noteNames, parseChordSymbol, pitchToScaleDegree, scaleByName, scaleTonesInDegreeOrder, spellChord, spellPitchClass, spellPitchClasses, spellScale, transposeChordSymbol, voiceLeadingCost } from './theory/index.cjs';
-export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from './index-BdeQ1r_p.cjs';
-export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from './index-DZ1M21do.cjs';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from './index-Dikst44v.cjs';
+export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from './index-CxqBQtH1.cjs';

package/dist/index.d.ts

@@ -1,14 +1,15 @@
-export { AnalyzedNote, ArrangementAnalysis, ArrangementOptions, ArrangementTrack, ChordMatch, Conflict, KeyMatch, TensionPoint, TheoryLabel, TrackAnalysis, TrackRole, VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, detectChord, detectChordBest, detectKey, romanToChord, tensionCurve } from './analyze/index.js';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from './function-2bJW1Zp_.js';
-export { C as CadenceHit, a as ChordSegment, b as ChordTimeline, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from './index-BMPxwjwV.js';
-export { IntervalQuality, JUST_RATIOS, Rng, TWELVE_TET, Tuning, centsBetweenFreq, centsOfSteps, classifyInterval, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents } from './core/index.js';
+export { AnalyzedNote, ArrangementAnalysis, ArrangementOptions, ArrangementTrack, Conflict, TensionPoint, TheoryLabel, TrackAnalysis, TrackRole, VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve } from './analyze/index.js';
+export { C as ChordMatch, D as DetectChordOptions, K as KeyMatch, d as detectChord, a as detectChordBest, b as detectKey } from './index-JnF4v9bx.js';
+export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from './function-DVH4Eusr.js';
+export { C as CadenceHit, a as ChordSegment, b as ChordTimeline, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from './index-DxvARIP2.js';
+export { DEFAULT_GENERATION_BUDGET, IndexedNoteEvent, IntervalQuality, JUST_RATIOS, NoteEventIndex, Rng, TWELVE_TET, Tuning, assertFiniteNumber, assertGenerationBudget, assertInteger, assertNoteEvent, assertNoteEvents, assertPositiveInt, assertRange, assertTimeSignature, centsBetweenFreq, centsOfSteps, classifyInterval, createNoteEventIndex, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents } from './core/index.js';
 export { B as BarPosition, T as TimeSignature, b as barPositionToBeat, a as beatToBarPosition, c as beatsPerBar, f as formatTimeSignature, i as isCompound, d as isStrongBeat, m as metricWeight, p as parseTimeSignature, e as pulsesPerBar, t as tuplet } from './index-Cl7mhOFM.js';
 export { N as NoteData, S as SpelledInterval, f as formatNote, m as midiToNote, n as noteToMidi, a as noteToPitchClass, p as parseNote, s as spelledInterval } from './index-CGMZNCx6.js';
 export { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.js';
 export { BassLineOptions, BassSegment, BassStyle, BorrowedChord, CounterMelodyOptions, DrumHit, DrumRole, DrumsOptions, EuclideanKick, GrooveFeel, GrooveSlot, GrooveStyle, GrooveTemplate, HarmonizeOptions, HarmonizeResult, HumanizeOptions, MelodyNote, MotifCell, MotifContour, MotifNote, MotifOptions, MotifTransform, ProgFunction, ProgStyle, ProgressionOptions, ProgressionPreset, RhythmEvent, RhythmOptions, Section, SubstituteOptions, Substitution, SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif } from './generate/index.js';
 export { Chord, Interval, Key, Note, Progression } from './model/index.js';
-export { C as ChordData, a as ChordQuality, b as ChordSpan, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from './index-CM5W4rcm.js';
-export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, d as VoicingOptions, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from './styled-D7BAx3S3.js';
+export { C as ChordData, a as ChordQuality, b as ChordSpan, P as PitchSpelling, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from './index-Bt4tOUD9.js';
+export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, d as VoicingOptions, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from './styled-DZ7GjShb.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, NAMED_SCALES, NATURAL_MINOR_MASK, OCTATONIC_HALF_WHOLE_MASK, OCTATONIC_WHOLE_HALF_MASK, PHRYGIAN_MASK, WHOLE_TONE_MASK, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, formatChordSymbol, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, maskFromOffsets, minorKey, nearestScaleTone, nextVoicing, noteNames, parseChordSymbol, pitchToScaleDegree, scaleByName, scaleTonesInDegreeOrder, spellChord, spellPitchClass, spellPitchClasses, spellScale, transposeChordSymbol, voiceLeadingCost } from './theory/index.js';
-export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from './index-CP3wAfEH.js';
-export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from './index-BreoJRw0.js';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from './index-Bg5dYMmZ.js';
+export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from './index-Jc0Ryi79.js';

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   chordTimelineFromNotes,
   detectCadences,
   tensionCurve
-} from "./chunk-5HTNMQW4.js";
+} from "./chunk-GOAW4VYL.js";
 import {
   JUST_RATIOS,
   TWELVE_TET,
@@ -16,7 +16,7 @@ import {
   justDeviationCents,
   nearestStep,
   ratioToCents
-} from "./chunk-ZXW5YIWK.js";
+} from "./chunk-AKLYPWIN.js";
 import {
   applyGrooveTemplate,
   developMotif,
@@ -34,14 +34,15 @@ import {
   progressionsByStyle,
   rhythmDensity,
   transformMotif
-} from "./chunk-R3S2LUBH.js";
+} from "./chunk-4MHA432G.js";
 import {
   createRng
-} from "./chunk-BHUT2S5G.js";
+} from "./chunk-62QZKCJQ.js";
 import {
   barPositionToBeat,
   beatToBarPosition,
   beatsPerBar,
+  createNoteEventIndex,
   formatTimeSignature,
   isCompound,
   isStrongBeat,
@@ -49,19 +50,19 @@ import {
   parseTimeSignature,
   pulsesPerBar,
   tuplet
-} from "./chunk-MSWFZF7J.js";
+} from "./chunk-I5R7ZBJS.js";
 import {
   Chord,
   Interval,
   Key,
   Note,
   Progression
-} from "./chunk-COKTX2G5.js";
+} from "./chunk-SGU7SPLK.js";
 import {
   modalInterchangePalette,
   negativeHarmonyMirror,
   substituteChord
-} from "./chunk-GQKN5KDT.js";
+} from "./chunk-IT2O4XFE.js";
 import {
   analyzeChord,
   borrowedSource,
@@ -77,16 +78,17 @@ import {
   parallelKey,
   romanToChord,
   secondaryDominant
-} from "./chunk-LN7ZZMD2.js";
+} from "./chunk-CHMXELDS.js";
+import "./chunk-N6IHQUOX.js";
 import {
   roleOf
-} from "./chunk-SDM3VJJ5.js";
+} from "./chunk-2ZWMSJH6.js";
 import {
   NoteSafety,
   ReasonFlag,
   enumerateSafePitches,
   evaluateSafety
-} from "./chunk-A4532ZFR.js";
+} from "./chunk-EH6EM37U.js";
 import {
   SATB_RANGES,
   availableTensions,
@@ -108,7 +110,7 @@ import {
   voiceChordStyled,
   voiceLeadingCost,
   voiceProgression
-} from "./chunk-XTC3X6MS.js";
+} from "./chunk-C5XYKUVG.js";
 import {
   formatNote,
   midiToNote,
@@ -161,17 +163,27 @@ import {
   pitchToScaleDegree,
   scaleByName,
   scaleTonesInDegreeOrder
-} from "./chunk-7Y7WF64D.js";
+} from "./chunk-MIWO425M.js";
 import {
+  DEFAULT_GENERATION_BUDGET,
   IntervalQuality,
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvent,
+  assertNoteEvents,
+  assertPositiveInt,
+  assertRange,
+  assertTimeSignature,
   classifyInterval,
   isConsonantInterval,
   isPerfectInterval
-} from "./chunk-CCBLVAPK.js";
+} from "./chunk-FBQK3ZQN.js";
 export {
   BLUES_MASK,
   CHROMATIC_MASK,
   Chord,
+  DEFAULT_GENERATION_BUDGET,
   DORIAN_MASK,
   HARMONIC_MINOR_MASK,
   Interval,
@@ -201,6 +213,14 @@ export {
   analyzeChord,
   analyzeVoice,
   applyGrooveTemplate,
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvent,
+  assertNoteEvents,
+  assertPositiveInt,
+  assertRange,
+  assertTimeSignature,
   availableTensions,
   avoidNotes,
   barPositionToBeat,
@@ -219,6 +239,7 @@ export {
   chordToRoman,
   chordToneRole,
   classifyInterval,
+  createNoteEventIndex,
   createRng,
   createsHiddenParallelPerfect,
   createsParallelOctave,

package/dist/model/index.cjs

@@ -28,6 +28,33 @@ __export(model_exports, {
 });
 module.exports = __toCommonJS(model_exports);
 
+// src/core/validation/index.ts
+var DEFAULT_GENERATION_BUDGET = 1e6;
+function assertFiniteNumber(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be finite; received ${value}`);
+  }
+  return value;
+}
+function assertInteger(value, name, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+  assertFiniteNumber(value, name);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+function assertPositiveInt(value, name, max = DEFAULT_GENERATION_BUDGET) {
+  return assertInteger(value, name, 1, max);
+}
+function assertGenerationBudget(estimated, name, limit = DEFAULT_GENERATION_BUDGET) {
+  assertFiniteNumber(estimated, name);
+  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);
+  if (estimated < 0 || estimated > limit) {
+    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);
+  }
+  return estimated;
+}
+
 // src/theory/scale/degrees.ts
 function pitchClass(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
@@ -252,8 +279,10 @@ function classifySeventh(thirdIc, fifthIc, seventhIc) {
 function stackThirds(degree, key, size) {
   const tones = scaleTonesInDegreeOrder(key);
   const length = tones.length;
-  if (length === 0) {
-    return { rootPc: pitchClass2(key.rootPc), quality: "maj", intervals: [0, 4, 7] };
+  if (length !== 7) {
+    throw new Error(
+      `diatonic chord stacking requires a heptatonic scale (received ${length} tones)`
+    );
   }
   const idx = (step) => ((degree + step) % length + length) % length;
   const rootPc = tones[idx(0)] ?? pitchClass2(key.rootPc);
@@ -280,12 +309,21 @@ function pitchClass3(value) {
 function uniquePitchClasses(pitches) {
   return [...new Set(pitches.map(pitchClass3))].sort((a, b) => a - b);
 }
-function detectChord(pitches) {
+function assertPitches(pitches) {
+  assertGenerationBudget(pitches.length, "detection pitches");
+  for (let index = 0; index < pitches.length; index += 1) {
+    assertFiniteNumber(pitches[index] ?? Number.NaN, `pitches[${index}]`);
+  }
+}
+function detectChord(pitches, opts = {}) {
+  assertPitches(pitches);
+  if (opts.bassPc !== void 0) assertFiniteNumber(opts.bassPc, "bassPc");
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];
   }
-  const bassPc = pitchClass3(Math.min(...pitches));
+  const inputKind = opts.input === void 0 || opts.input === "auto" ? pitches.every((pitch) => Number.isInteger(pitch) && pitch >= 0 && pitch <= 11) ? "pitchClass" : "midi" : opts.input;
+  const bassPc = opts.bassPc !== void 0 ? pitchClass3(opts.bassPc) : inputKind === "midi" ? pitchClass3(pitches.reduce((lowest, pitch) => Math.min(lowest, pitch), Infinity)) : void 0;
   const inputSet = new Set(input);
   const matches = [];
   const qualities = chordQualities();
@@ -300,8 +338,8 @@ function detectChord(pitches) {
         continue;
       }
       const extraPcs = input.filter((pc) => !toneSet.has(pc));
-      const bassIndex = chord.intervals.findIndex((iv) => pitchClass3(rootPc + iv) === bassPc);
-      const inversion = bassIndex > 0 ? bassIndex : 0;
+      const bassIndex = bassPc === void 0 ? -1 : chord.intervals.findIndex((iv) => pitchClass3(rootPc + iv) === bassPc);
+      const inversion = bassPc === void 0 ? null : bassIndex > 0 ? bassIndex : 0;
       const match = {
         rootPc,
         quality,
@@ -310,7 +348,7 @@ function detectChord(pitches) {
         exact: extraPcs.length === 0 && missingPcs.length === 0,
         inversion
       };
-      if (inversion > 0) {
+      if (bassPc !== void 0 && bassPc !== rootPc) {
         match.bassPc = bassPc;
       }
       matches.push(match);
@@ -332,8 +370,8 @@ function detectChord(pitches) {
   });
   return matches;
 }
-function detectChordBest(pitches) {
-  const best = detectChord(pitches)[0];
+function detectChordBest(pitches, opts = {}) {
+  const best = detectChord(pitches, opts)[0];
   if (!best) {
     return null;
   }
@@ -469,11 +507,16 @@ function parseSimpleRoman(text, key) {
   if (canonical !== void 0) {
     return { rootPc, quality: canonical, inversion: 0 };
   }
-  const isDim = /o|°|dim/.test(suffix);
-  const isAug = /\+|aug/.test(suffix);
-  const isHalfDim = /ø/.test(suffix);
-  const explicitMaj7 = /maj7|M7/.test(suffix);
-  const figures = suffix.replace(/maj7|M7/g, "").replace(/[^0-9]/g, "");
+  const parsedSuffix = /^(o|°|dim|ø|\+|aug)?(maj7|M7)?(65|64|43|42|7|6|2)?$/.exec(suffix);
+  if (!parsedSuffix) {
+    throw new Error(`Unsupported suffix "${suffix}" in Roman numeral: ${text}`);
+  }
+  const qualityMarker = parsedSuffix[1] ?? "";
+  const isDim = qualityMarker === "o" || qualityMarker === "\xB0" || qualityMarker === "dim";
+  const isAug = qualityMarker === "+" || qualityMarker === "aug";
+  const isHalfDim = qualityMarker === "\xF8";
+  const explicitMaj7 = parsedSuffix[2] !== void 0;
+  const figures = parsedSuffix[3] ?? "";
   if (figures !== "" && !INVERSION_FIGURES.has(figures)) {
     throw new Error(`Unsupported figured-bass or extension "${figures}" in Roman numeral: ${text}`);
   }
@@ -1055,10 +1098,58 @@ function spellPitchClass(pc, tonic, key) {
 function spellScale(tonic, key) {
   return scaleTonesInDegreeOrder(key).map((pc) => spellPitchClass(pc, tonic, key));
 }
+function chordLetterOffset(interval, chord) {
+  switch (interval) {
+    case 0:
+    case 12:
+      return 0;
+    case 1:
+    case 2:
+    case 13:
+    case 14:
+      return 1;
+    case 3:
+    case 4:
+    case 15:
+    case 16:
+      return 2;
+    case 5:
+    case 17:
+    case 18:
+      return 3;
+    case 6:
+    case 7:
+    case 8:
+    case 19:
+      return 4;
+    case 9:
+      return chord.quality === "dim7" ? 6 : 5;
+    case 20:
+    case 21:
+      return 5;
+    case 10:
+    case 11:
+    case 22:
+    case 23:
+      return 6;
+    default: {
+      const octaves = Math.floor(Math.max(0, interval) / 12);
+      const simple = mod124(interval);
+      const simpleOffset = [0, 1, 1, 2, 2, 3, 4, 4, 4, 5, 6, 6][simple] ?? 0;
+      return octaves * 7 + simpleOffset;
+    }
+  }
+}
+function spellChordFromRoot(chord, root) {
+  return chord.intervals.map((interval) => {
+    const letter = mod72(root.letter + chordLetterOffset(interval, chord));
+    const pc = mod124(chord.rootPc + interval);
+    return { letter, alter: alterFor(letter, pc) };
+  });
+}
 function spellChord(chord, tonic, key) {
-  return chord.intervals.map(
-    (interval) => spellPitchClass(mod124(chord.rootPc + interval), tonic, key)
-  );
+  const root = spellPitchClass(chord.rootPc, tonic, key);
+  return spellChordFromRoot(chord, root);
 }
 
 // src/theory/symbol/index.ts
@@ -1388,12 +1479,23 @@ function resolveRanges(opts) {
     if (opts.ranges.length === 0) {
       throw new Error("ranges must contain at least one voice range");
     }
-    return opts.ranges.map((range) => ({ ...range }));
+    assertGenerationBudget(opts.ranges.length, "voice ranges", 128);
+    return opts.ranges.map((range, index) => {
+      assertFiniteNumber(range.min, `ranges[${index}].min`);
+      assertFiniteNumber(range.max, `ranges[${index}].max`);
+      if (range.min > range.max) {
+        throw new RangeError(`ranges[${index}].min must not exceed max`);
+      }
+      assertGenerationBudget(
+        Math.floor(range.max) - Math.ceil(range.min) + 1,
+        `ranges[${index}] span`,
+        4096
+      );
+      return { ...range };
+    });
   }
   const voices = opts?.voices ?? 4;
-  if (voices < 1) {
-    throw new Error("voices must be at least 1");
-  }
+  assertPositiveInt(voices, "voices", 128);
   if (voices === 4) {
     return SATB_RANGES.map((range) => ({ ...range }));
   }
@@ -1412,6 +1514,8 @@ function resolveRanges(opts) {
 function voiceChord(chord, opts) {
   const ranges = resolveRanges(opts);
   const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
+  assertFiniteNumber(maxSpacing, "maxSpacing");
+  if (maxSpacing < 0) throw new RangeError("maxSpacing must be non-negative");
   const candidates = enumerateVoicings(chord, ranges, maxSpacing);
   let best;
   let bestScore = Number.POSITIVE_INFINITY;
@@ -1436,8 +1540,11 @@ function voiceChord(chord, opts) {
   return best;
 }
 function voiceProgression(chords, opts) {
+  assertGenerationBudget(chords.length * 4e3, "voiced progression search");
   const ranges = resolveRanges(opts);
   const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
+  assertFiniteNumber(maxSpacing, "maxSpacing");
+  if (maxSpacing < 0) throw new RangeError("maxSpacing must be non-negative");
   const result = [];
   let prev;
   for (const chord of chords) {
@@ -1522,7 +1629,12 @@ function nearestPc(target, pcs) {
 }
 function voiceChordStyled(chord, opts) {
   const style = opts?.style ?? "close";
-  const base = 12 * ((opts?.octave ?? DEFAULT_STYLE_OCTAVE) + 1);
+  const octave = opts?.octave ?? DEFAULT_STYLE_OCTAVE;
+  assertInteger(octave, "styled voicing octave", -10, 10);
+  if (opts?.topNote !== void 0) {
+    assertFiniteNumber(opts.topNote, "styled voicing topNote");
+  }
+  const base = 12 * (octave + 1);
   const rootPc = pitchClass6(chord.rootPc);
   const bassPc = pitchClass6(chord.bassPc ?? chord.rootPc);
   const omitRoot = style === "rootless" || opts?.rootless === true;
@@ -1538,11 +1650,11 @@ function voiceChordStyled(chord, opts) {
     const guide = roles.includes("seventh") ? "seventh" : roles.includes("sixth") ? "sixth" : "fifth";
     order = order.filter((_pc, i) => {
       const role = roles[i];
-      return role === "root" || role === "third" || role === guide;
+      return _pc === bassPc || role === "root" || role === "third" || role === guide;
     });
   }
   if (omitRoot) {
-    order = order.filter((pc) => pc !== rootPc);
+    order = order.filter((pc) => pc !== rootPc || chord.bassPc !== void 0 && pc === bassPc);
   }
   if (order.length === 0) {
     return [];
@@ -1571,6 +1683,18 @@ function voiceChordStyled(chord, opts) {
   } else if (style === "drop3" && stack.length >= 3) {
     stack[stack.length - 3] = (stack[stack.length - 3] ?? 0) - 12;
   }
+  if (chord.bassPc !== void 0) {
+    const bassIndexInStack = stack.findIndex((pitch) => pitchClass6(pitch) === bassPc);
+    if (bassIndexInStack >= 0) {
+      const otherLowest = Math.min(
+        ...stack.filter((_pitch, index) => index !== bassIndexInStack),
+        Number.POSITIVE_INFINITY
+      );
+      while ((stack[bassIndexInStack] ?? 0) >= otherLowest) {
+        stack[bassIndexInStack] = (stack[bassIndexInStack] ?? 0) - 12;
+      }
+    }
+  }
   return stack.sort((a, b) => a - b);
 }
 
@@ -1866,7 +1990,11 @@ var Chord = class _Chord {
    * @param key Optional key context for analysis methods.
    */
   constructor(data, key) {
-    this.#data = copyChord(data);
+    const copy = copyChord(data);
+    if (copy.rootSpelling === void 0 && key !== void 0) {
+      copy.rootSpelling = spellPitchClass(copy.rootPc, key.tonic.data, key.scale);
+    }
+    this.#data = copy;
     this.#key = key;
   }
   /**
@@ -1878,8 +2006,13 @@ var Chord = class _Chord {
    * @returns The chord (without key context).
    */
   static of(root, quality, bass) {
-    const rootPc = typeof root === "string" ? Note.of(root).pitchClass : root;
-    return new _Chord(makeChord(rootPc, quality, bass));
+    if (typeof root === "string") {
+      const rootNote = Note.of(root);
+      const data = makeChord(rootNote.pitchClass, quality, bass);
+      data.rootSpelling = { letter: rootNote.letter, alter: rootNote.alter };
+      return new _Chord(data);
+    }
+    return new _Chord(makeChord(root, quality, bass));
   }
   /**
    * Wrap an existing plain chord object.
@@ -1906,8 +2039,8 @@ var Chord = class _Chord {
    * @param pitches MIDI pitches or bare pitch classes.
    * @returns Ranked chord interpretations (may be empty).
    */
-  static detect(pitches) {
-    return detectChord(pitches).map(
+  static detect(pitches, opts) {
+    return detectChord(pitches, opts).map(
       (match) => new _Chord(makeChord(match.rootPc, match.quality, match.bassPc))
     );
   }
@@ -1917,8 +2050,8 @@ var Chord = class _Chord {
    * @param pitches MIDI pitches or bare pitch classes.
    * @returns The top-ranked chord, or null when nothing matches.
    */
-  static detectBest(pitches) {
-    const best = detectChordBest(pitches);
+  static detectBest(pitches, opts) {
+    const best = detectChordBest(pitches, opts);
     return best === null ? null : new _Chord(best);
   }
   /** The root pitch class (0..11). */
@@ -2076,8 +2209,14 @@ var Chord = class _Chord {
     const data = copyChord(this.#data);
     if (index === 0) {
       delete data.bassPc;
+      delete data.bassSpelling;
     } else {
       data.bassPc = mod125(this.#data.rootPc + (intervals[index] ?? 0));
+      const rootSpelling = data.rootSpelling ?? (this.#key ? spellPitchClass(data.rootPc, this.#key.tonic.data, this.#key.scale) : spellPitchClassBare(data.rootPc, "sharp"));
+      const bassSpelling = spellChordFromRoot(data, rootSpelling)[index];
+      if (bassSpelling !== void 0) {
+        data.bassSpelling = bassSpelling;
+      }
     }
     return new _Chord(data, this.#key);
   }