@libraz/libcantus 0.9.0 → 0.9.1

package/dist/index.js

@@ -390,12 +390,24 @@ function isLeadingToneResolution(prev, cur, key) {
 }
 
 // src/analysis/index.ts
+var EPS = 1e-9;
 function pitchClass4(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
 function intervalAboveRoot(pitch, chord) {
   return ((pitchClass4(pitch) - pitchClass4(chord.rootPc)) % 12 + 12) % 12;
 }
+function intervalAboveBass(pitch, others, chord) {
+  let bass = Number.POSITIVE_INFINITY;
+  for (const ov of others) {
+    bass = Math.min(bass, ov.pitch);
+  }
+  if (Number.isFinite(bass) && bass < pitch) {
+    return ((pitch - bass) % 12 + 12) % 12;
+  }
+  const ref = chord.bassPc ?? chord.rootPc;
+  return ((pitchClass4(pitch) - pitchClass4(ref)) % 12 + 12) % 12;
+}
 function tensionDegree(ic) {
   if (ic === 1 || ic === 2) {
     return 9;
@@ -440,8 +452,10 @@ function analyzeVoice(voice, chordAtBeat, key, otherVoicesAtBeat) {
     if (!note) {
       continue;
     }
-    const prev = i > 0 ? voice[i - 1] : void 0;
-    const next = i + 1 < voice.length ? voice[i + 1] : void 0;
+    const prevNote = i > 0 ? voice[i - 1] : void 0;
+    const nextNote = i + 1 < voice.length ? voice[i + 1] : void 0;
+    const prev = prevNote !== void 0 && prevNote.startBeat < note.startBeat - EPS ? prevNote : void 0;
+    const next = nextNote !== void 0 && nextNote.startBeat > note.startBeat + EPS ? nextNote : void 0;
     const chord = chordAtBeat(note.startBeat);
     const labels = [];
     const member = isChordMember(note.pitch, chord);
@@ -460,11 +474,12 @@ function analyzeVoice(voice, chordAtBeat, key, otherVoicesAtBeat) {
       const prevChord = chordAtBeat(prev.startBeat);
       const prepared = prev.pitch === note.pitch && isChordMember(prev.pitch, prevChord);
       const resolves = isStep(next.pitch, note.pitch);
-      const verticallyDissonant = otherVoicesAtBeat(note.startBeat).some(
+      const others = otherVoicesAtBeat(note.startBeat);
+      const verticallyDissonant = others.some(
         (ov) => createsVerticalDissonance(note.pitch, ov.pitch, true)
       );
       if (prepared && verticallyDissonant && resolves) {
-        const ic = intervalAboveRoot(note.pitch, chord);
+        const ic = intervalAboveBass(note.pitch, others, chord);
         const sus = suspensionType(ic, next.pitch - note.pitch);
         sus.resolveTo = next.pitch;
         labels.push(sus);
@@ -638,11 +653,43 @@ function seventhQuality(base, halfDim) {
   return base === "maj" ? "dom7" : "min7";
 }
 var INVERSION_FIGURES = /* @__PURE__ */ new Set(["6", "64", "65", "43", "42", "2", "7"]);
-var EXTENSION_FIGURES = {
-  "9": "dom9",
-  "11": "11",
-  "13": "13"
+var ROMAN_STYLE = {
+  maj: { lower: false, suffix: "" },
+  min: { lower: true, suffix: "" },
+  dim: { lower: true, suffix: "o" },
+  aug: { lower: false, suffix: "+" },
+  maj7: { lower: false, suffix: "maj7" },
+  min7: { lower: true, suffix: "7" },
+  dom7: { lower: false, suffix: "7" },
+  dim7: { lower: true, suffix: "o7" },
+  m7b5: { lower: true, suffix: "\xF87" },
+  minMaj7: { lower: true, suffix: "maj7" },
+  aug7: { lower: false, suffix: "+7" },
+  augMaj7: { lower: false, suffix: "+maj7" },
+  majb5: { lower: false, suffix: "b5" },
+  "6": { lower: false, suffix: "add6" },
+  min6: { lower: true, suffix: "add6" },
+  "6/9": { lower: false, suffix: "69" },
+  sus2: { lower: false, suffix: "sus2" },
+  sus4: { lower: false, suffix: "sus4" },
+  add9: { lower: false, suffix: "add9" },
+  add11: { lower: false, suffix: "add11" },
+  maj9: { lower: false, suffix: "maj9" },
+  min9: { lower: true, suffix: "9" },
+  dom9: { lower: false, suffix: "9" },
+  "7b9": { lower: false, suffix: "7b9" },
+  "7#9": { lower: false, suffix: "7#9" },
+  "7#11": { lower: false, suffix: "7#11" },
+  "7b13": { lower: false, suffix: "7b13" },
+  "11": { lower: false, suffix: "11" },
+  "13": { lower: false, suffix: "13" },
+  "5": { lower: false, suffix: "5" }
 };
+var SUFFIX_QUALITY = new Map(
+  Object.entries(ROMAN_STYLE).map(
+    ([quality, style]) => [`${style.lower ? "l" : "u"}:${style.suffix}`, quality]
+  )
+);
 function parseInversion(figures) {
   if (figures === "65") {
     return { inversion: 1, seventh: true };
@@ -678,15 +725,15 @@ function parseSimpleRoman(text, key) {
   const isUpper = (match[2] ?? "")[0] === (match[2] ?? "")[0]?.toUpperCase();
   const suffix = match[3] ?? "";
   const rootPc = mod12(degreeRootPc(degreeNumber, key) + accidental);
+  const canonical = SUFFIX_QUALITY.get(`${isUpper ? "u" : "l"}:${suffix}`);
+  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 extension = EXTENSION_FIGURES[figures];
-  if (extension !== void 0) {
-    return { rootPc, quality: extension, inversion: 0 };
-  }
   if (figures !== "" && !INVERSION_FIGURES.has(figures)) {
     throw new Error(`Unsupported figured-bass or extension "${figures}" in Roman numeral: ${text}`);
   }
@@ -702,7 +749,7 @@ function parseSimpleRoman(text, key) {
   }
   let quality;
   if (explicitMaj7) {
-    quality = base === "min" ? "minMaj7" : "maj7";
+    quality = base === "min" ? "minMaj7" : base === "aug" ? "augMaj7" : "maj7";
   } else if (hasSeventh) {
     quality = seventhQuality(base, isHalfDim);
   } else if (base === "dim") {
@@ -734,30 +781,7 @@ function romanToChord(text, key) {
   return chordFromParsed(parseSimpleRoman(trimmed, key));
 }
 function romanStyle(quality) {
-  switch (quality) {
-    case "min":
-      return { lower: true, suffix: "" };
-    case "dim":
-      return { lower: true, suffix: "o" };
-    case "aug":
-      return { lower: false, suffix: "+" };
-    case "maj7":
-      return { lower: false, suffix: "maj7" };
-    case "dom7":
-      return { lower: false, suffix: "7" };
-    case "min7":
-      return { lower: true, suffix: "7" };
-    case "m7b5":
-      return { lower: true, suffix: "\xF87" };
-    case "dim7":
-      return { lower: true, suffix: "o7" };
-    case "minMaj7":
-      return { lower: true, suffix: "maj7" };
-    case "maj":
-      return { lower: false, suffix: "" };
-    default:
-      return { lower: false, suffix: quality };
-  }
+  return ROMAN_STYLE[quality];
 }
 function romanSpelling(rootPc, key) {
   const tones = scaleTonesInDegreeOrder(key);
@@ -792,6 +816,9 @@ function baseMarker(quality) {
   if (quality === "aug" || quality === "aug7") {
     return "+";
   }
+  if (quality === "augMaj7") {
+    return "+maj7";
+  }
   if (quality === "maj7" || quality === "minMaj7") {
     return "maj7";
   }
@@ -799,6 +826,17 @@ function baseMarker(quality) {
 }
 var TRIAD_FIGURES = { 1: "6", 2: "64" };
 var SEVENTH_FIGURES = { 1: "65", 2: "43", 3: "42" };
+var TRIAD_FIGURE_QUALITIES = /* @__PURE__ */ new Set(["maj", "min", "dim", "aug"]);
+var SEVENTH_FIGURE_QUALITIES = /* @__PURE__ */ new Set([
+  "maj7",
+  "min7",
+  "dom7",
+  "dim7",
+  "m7b5",
+  "minMaj7",
+  "aug7",
+  "augMaj7"
+]);
 function chordToRoman(chord, key) {
   const { degreeNumber, accidental } = romanSpelling(chord.rootPc, key);
   const { lower, suffix } = romanStyle(chord.quality);
@@ -812,8 +850,7 @@ function chordToRoman(chord, key) {
     }
   }
   if (inversion > 0) {
-    const isSeventh = chord.intervals.length >= 4;
-    const figure = (isSeventh ? SEVENTH_FIGURES : TRIAD_FIGURES)[inversion];
+    const figure = SEVENTH_FIGURE_QUALITIES.has(chord.quality) ? SEVENTH_FIGURES[inversion] : TRIAD_FIGURE_QUALITIES.has(chord.quality) ? TRIAD_FIGURES[inversion] : void 0;
     if (figure !== void 0) {
       return `${accidental}${cased}${baseMarker(chord.quality)}${figure}`;
     }
@@ -912,13 +949,13 @@ function secondaryDominant(targetDegree, key) {
 }
 
 // src/meter/index.ts
-var EPS = 1e-9;
+var EPS2 = 1e-9;
 function isMultiple(value, unit) {
   if (unit === 0) {
     return false;
   }
   const ratio = value / unit;
-  return Math.abs(ratio - Math.round(ratio)) < EPS;
+  return Math.abs(ratio - Math.round(ratio)) < EPS2;
 }
 function parseTimeSignature(text) {
   const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(text);
@@ -950,6 +987,29 @@ function pulseBeats(ts) {
 function pulsesPerBar(ts) {
   return beatsPerBar(ts) / pulseBeats(ts);
 }
+function isValidGrouping(grouping, pulses) {
+  if (grouping.length === 0) {
+    return false;
+  }
+  let sum = 0;
+  for (const g of grouping) {
+    if (!Number.isInteger(g) || g <= 0) {
+      return false;
+    }
+    sum += g;
+  }
+  return sum === pulses;
+}
+function isGroupHead(grouping, pulseIndex) {
+  let acc = 0;
+  for (const g of grouping) {
+    if (acc === pulseIndex) {
+      return true;
+    }
+    acc += g;
+  }
+  return false;
+}
 function beatToBarPosition(beatInQuarters, ts) {
   const barLen = beatsPerBar(ts);
   const bar = Math.floor(beatInQuarters / barLen);
@@ -969,6 +1029,15 @@ function metricWeight(beatInQuarters, ts) {
   if (pulseIndex === 0) {
     return 3;
   }
+  const grouping = ts.grouping;
+  if (grouping !== void 0) {
+    if (!isValidGrouping(grouping, pulses)) {
+      throw new Error(
+        `Invalid grouping [${grouping.join(", ")}] for ${formatTimeSignature(ts)}: entries must be positive integers summing to ${pulses}`
+      );
+    }
+    return isGroupHead(grouping, pulseIndex) ? 2 : 1;
+  }
   if (pulses % 2 === 0 && pulseIndex === pulses / 2) {
     return 2;
   }
@@ -1129,7 +1198,7 @@ function evaluateInternal(q, collectSuggestions) {
       if (ov.prevPitch === void 0) {
         continue;
       }
-      if (createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch) || createsParallelOctave(prev, pitch, ov.prevPitch, ov.pitch)) {
+      if (createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {
         reasons |= 2048 /* ParallelPerfect */;
         raise(parallelSeverity);
       }
@@ -1261,7 +1330,7 @@ function detectChord(pitches) {
         quality,
         missingPcs,
         extraPcs,
-        exact: extraPcs.length === 0,
+        exact: extraPcs.length === 0 && missingPcs.length === 0,
         inversion
       };
       if (inversion > 0) {
@@ -1293,38 +1362,49 @@ function detectChordBest(pitches) {
   }
   return makeChord(best.rootPc, best.quality, best.bassPc);
 }
+var MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MINOR_MASK];
 function detectKey(pitches) {
   const input = uniquePitchClasses(pitches);
+  if (input.length === 0) {
+    return [];
+  }
   const counts = /* @__PURE__ */ new Map();
   for (const pc of pitches.map(pitchClass6)) {
     counts.set(pc, (counts.get(pc) ?? 0) + 1);
   }
-  const total = pitches.length || 1;
+  const total = pitches.length;
   const results = [];
   for (let tonic = 0; tonic < 12; tonic += 1) {
     for (const mode of ["major", "minor"]) {
       const key = mode === "major" ? majorKey(tonic) : minorKey(tonic);
+      const masks = mode === "major" ? [MAJOR_MASK] : MINOR_MASK_VARIANTS;
       let inScale = 0;
-      let weighted = 0;
-      for (const pc of input) {
-        const offset = (pc - tonic + 12) % 12;
-        if (key.modeMask12 >> offset & 1) {
-          inScale += 1;
+      let weighted = Number.NEGATIVE_INFINITY;
+      for (const mask of masks) {
+        let variantInScale = 0;
+        let variantWeighted = 0;
+        for (const pc of input) {
+          const offset = (pc - tonic + 12) % 12;
+          if (mask >> offset & 1) {
+            variantInScale += 1;
+          }
         }
-      }
-      for (const [pc, count] of counts) {
-        const offset = (pc - tonic + 12) % 12;
-        if (key.modeMask12 >> offset & 1) {
-          weighted += count;
+        for (const [pc, count] of counts) {
+          const offset = (pc - tonic + 12) % 12;
+          if (mask >> offset & 1) {
+            variantWeighted += count;
+          }
         }
-        if (pc === tonic) {
-          weighted += count * 0.5;
+        if (variantWeighted > weighted) {
+          weighted = variantWeighted;
+          inScale = variantInScale;
         }
       }
+      weighted += (counts.get(tonic) ?? 0) * 0.5;
       results.push({
         key,
         mode,
-        fit: input.length === 0 ? 0 : inScale / input.length,
+        fit: inScale / input.length,
         score: weighted / total
       });
     }
@@ -1357,7 +1437,7 @@ function segmentLookup(segments) {
     return null;
   };
 }
-var EPS2 = 1e-9;
+var EPS3 = 1e-9;
 var NOISE_THRESHOLD_RATIO = 0.2;
 var MAX_DETECTION_PCS = 6;
 var FALLBACK_PCS = 3;
@@ -1399,11 +1479,11 @@ function analyzeWindow(notes, windowStart, windowEnd, ts, key) {
   for (const note of notes) {
     const noteEnd = note.startBeat + note.durationBeat;
     const overlap = Math.min(noteEnd, windowEnd) - Math.max(note.startBeat, windowStart);
-    if (overlap <= EPS2) {
+    if (overlap <= EPS3) {
       continue;
     }
     const velocityFactor = note.velocity !== void 0 ? note.velocity / 127 : 1;
-    const onsetInWindow = note.startBeat >= windowStart - EPS2 && note.startBeat < windowEnd - EPS2;
+    const onsetInWindow = note.startBeat >= windowStart - EPS3 && note.startBeat < windowEnd - EPS3;
     const accent = onsetInWindow ? 1 + metricWeight(note.startBeat, ts) / 3 : 1;
     const pc = pitchClass7(note.pitch);
     weights[pc] = (weights[pc] ?? 0) + overlap * velocityFactor * accent;
@@ -1417,7 +1497,7 @@ function analyzeWindow(notes, windowStart, windowEnd, ts, key) {
     totalWeight += w;
     maxWeight = Math.max(maxWeight, w);
   }
-  if (totalWeight <= EPS2) {
+  if (totalWeight <= EPS3) {
     return null;
   }
   const ranked = weights.map((weight, pc) => ({ pc, weight })).filter(({ weight }) => weight > 0).sort((a, b) => b.weight - a.weight || a.pc - b.pc);
@@ -1454,21 +1534,22 @@ function chordTimelineFromNotes(notes, opts = {}) {
   if (!(harmonicRhythm > 0)) {
     throw new Error(`Invalid harmonic rhythm: ${harmonicRhythm}`);
   }
-  const lastNoteEnd = notes.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  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 = [];
   const segmentConfidence = [];
-  const windowCount = Math.max(0, Math.ceil(totalBeats / harmonicRhythm - EPS2));
+  const windowCount = Math.max(0, Math.ceil(totalBeats / harmonicRhythm - EPS3));
   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;
     }
     const last = segments[segments.length - 1];
-    if (last && sameChord(last.chord, inferred.chord) && Math.abs(last.endBeat - start) < EPS2) {
+    if (last && sameChord(last.chord, inferred.chord) && Math.abs(last.endBeat - start) < EPS3) {
       const lastLength = last.endBeat - last.startBeat;
       const length = end - start;
       const lastConfidence = segmentConfidence[segmentConfidence.length - 1] ?? 0;
@@ -1493,6 +1574,9 @@ function detectCadences(timeline, key) {
     if (!prev || !cur) {
       continue;
     }
+    if (Math.abs(cur.startBeat - prev.endBeat) > EPS3) {
+      continue;
+    }
     const type = detectCadence(prev.chord, cur.chord, key);
     if (type !== null) {
       hits.push({ atBeat: cur.startBeat, type, from: prev.chord, to: cur.chord });
@@ -1502,67 +1586,101 @@ function detectCadences(timeline, key) {
 }
 
 // src/arrange/index.ts
-var EPS3 = 1e-9;
+var EPS4 = 1e-9;
 function pitchClass8(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
 function covers(note, beat) {
-  return beat >= note.startBeat - EPS3 && beat < note.endBeat - EPS3;
+  return beat >= note.startBeat - EPS4 && beat < note.endBeat - EPS4;
 }
 function poolNotes(tracks) {
   const notes = [];
   for (const track of tracks) {
     for (const note of track.notes) {
-      notes.push(note);
+      if (note.durationBeat > 0) {
+        notes.push(note);
+      }
     }
   }
   return notes;
 }
+function splitIntoSubVoices(ordered) {
+  const lanes = [];
+  for (const note of ordered) {
+    const lane = lanes.find((candidate) => {
+      const last = candidate[candidate.length - 1];
+      return last !== void 0 && last.startBeat + last.durationBeat <= note.startBeat + EPS4;
+    });
+    if (lane) {
+      lane.push(note);
+    } else {
+      lanes.push([note]);
+    }
+  }
+  return lanes;
+}
 function prepareTracks(tracks) {
   let nextId = 0;
   return tracks.map((track, index) => {
-    const ordered = [...track.notes].sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
-    const voice = ordered.map((note) => ({ ...note, id: nextId++ }));
-    const sounding = ordered.map((note, i) => {
-      const prev = i > 0 ? ordered[i - 1] : void 0;
-      return {
-        pitch: note.pitch,
-        prevPitch: prev?.pitch,
-        startBeat: note.startBeat,
-        endBeat: note.startBeat + note.durationBeat
-      };
-    });
+    const ordered = track.notes.filter((note) => note.durationBeat > 0).sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch).map((note) => ({ ...note, id: nextId++ }));
+    const voices = splitIntoSubVoices(ordered).map((voice) => ({
+      voice,
+      sounding: voice.map((note, i) => {
+        const prev = i > 0 ? voice[i - 1] : void 0;
+        return {
+          pitch: note.pitch,
+          prevPitch: prev?.pitch,
+          startBeat: note.startBeat,
+          endBeat: note.startBeat + note.durationBeat
+        };
+      })
+    }));
     return {
       name: track.name ?? `track ${index + 1}`,
       role: track.role ?? "other",
-      voice,
-      sounding
+      voices
     };
   });
 }
-function otherVoicesSounding(prepared, excludeIndex, beat) {
+function otherVoicesSounding(prepared, excludeTrack, excludeVoice, beat) {
   const out = [];
   for (let t = 0; t < prepared.length; t += 1) {
-    if (t === excludeIndex) {
-      continue;
-    }
     const track = prepared[t];
     if (!track) {
       continue;
     }
-    for (const note of track.sounding) {
-      if (!covers(note, beat)) {
+    for (let v = 0; v < track.voices.length; v += 1) {
+      if (t === excludeTrack && v === excludeVoice) {
+        continue;
+      }
+      const subVoice = track.voices[v];
+      if (!subVoice) {
         continue;
       }
-      const snap = { pitch: note.pitch };
-      if (note.prevPitch !== void 0) {
-        snap.prevPitch = note.prevPitch;
+      for (const note of subVoice.sounding) {
+        if (!covers(note, beat)) {
+          continue;
+        }
+        const snap = { pitch: note.pitch };
+        if (note.prevPitch !== void 0) {
+          snap.prevPitch = note.prevPitch;
+        }
+        out.push(snap);
       }
-      out.push(snap);
     }
   }
   return out;
 }
+function evaluationBeats(note, timeline) {
+  const noteEnd = note.startBeat + note.durationBeat;
+  const beats = [note.startBeat];
+  for (const segment of timeline.segments) {
+    if (segment.startBeat > note.startBeat + EPS4 && segment.startBeat < noteEnd - EPS4) {
+      beats.push(segment.startBeat);
+    }
+  }
+  return beats;
+}
 function analyzeArrangement(tracks, opts = {}) {
   const ts = opts.ts ?? parseTimeSignature("4/4");
   const profile = opts.profile ?? "pop";
@@ -1581,36 +1699,48 @@ function analyzeArrangement(tracks, opts = {}) {
     if (!track) {
       continue;
     }
-    const notes = analyzeVoice(
-      track.voice,
-      timeline.at,
-      key,
-      (beat) => otherVoicesSounding(prepared, t, beat)
-    );
-    trackAnalyses.push({ name: track.name, role: track.role, notes });
-    for (const note of track.voice) {
-      const result = evaluateSafety({
-        profile,
-        candidatePitch: note.pitch,
-        chord: timeline.at(note.startBeat),
-        key,
-        otherVoices: otherVoicesSounding(prepared, t, note.startBeat),
-        strongBeat: isStrongBeat(note.startBeat, ts)
-      });
-      if (result.safety !== 0 /* Safe */) {
-        const conflict = {
-          beat: note.startBeat,
-          trackName: track.name,
-          pitch: note.pitch,
-          safety: result.safety,
-          reasons: result.reasons
-        };
-        if (result.rationale !== void 0) {
-          conflict.rationale = result.rationale;
+    const notes = [];
+    for (let v = 0; v < track.voices.length; v += 1) {
+      const subVoice = track.voices[v];
+      if (!subVoice) {
+        continue;
+      }
+      notes.push(
+        ...analyzeVoice(
+          subVoice.voice,
+          timeline.at,
+          key,
+          (beat) => otherVoicesSounding(prepared, t, v, beat)
+        )
+      );
+      for (const note of subVoice.voice) {
+        for (const beat of evaluationBeats(note, timeline)) {
+          const result = evaluateSafety({
+            profile,
+            candidatePitch: note.pitch,
+            chord: timeline.at(beat),
+            key,
+            otherVoices: otherVoicesSounding(prepared, t, v, beat),
+            strongBeat: isStrongBeat(beat, ts)
+          });
+          if (result.safety !== 0 /* Safe */) {
+            const conflict = {
+              beat,
+              trackName: track.name,
+              pitch: note.pitch,
+              safety: result.safety,
+              reasons: result.reasons
+            };
+            if (result.rationale !== void 0) {
+              conflict.rationale = result.rationale;
+            }
+            conflicts.push(conflict);
+          }
         }
-        conflicts.push(conflict);
       }
     }
+    notes.sort((a, b) => a.noteId - b.noteId);
+    trackAnalyses.push({ name: track.name, role: track.role, notes });
   }
   conflicts.sort((a, b) => b.safety - a.safety || a.beat - b.beat);
   return { key, timeline, segmentConfidence, cadences, tracks: trackAnalyses, conflicts };
@@ -1643,7 +1773,7 @@ function tensionCurve(tracks, opts = {}) {
   });
   const prepared = prepareTracks(tracks);
   const points = [];
-  const sampleCount = Math.max(0, Math.ceil(totalBeats / step - EPS3));
+  const sampleCount = Math.max(0, Math.ceil(totalBeats / step - EPS4));
   for (let i = 0; i < sampleCount; i += 1) {
     const beat = i * step;
     points.push({ beat, tension: sampleTension(prepared, timeline, key, ts, profile, beat) });
@@ -1657,9 +1787,11 @@ function allSounding(prepared, beat) {
     if (!track) {
       continue;
     }
-    for (const note of track.sounding) {
-      if (covers(note, beat)) {
-        out.push({ pitch: note.pitch, track: t });
+    for (const subVoice of track.voices) {
+      for (const note of subVoice.sounding) {
+        if (covers(note, beat)) {
+          out.push({ pitch: note.pitch, track: t });
+        }
       }
     }
   }
@@ -1735,7 +1867,7 @@ var DEFAULT_OCTAVE = 2;
 var STRONG_VELOCITY = 100;
 var WEAK_VELOCITY = 80;
 var PICKUP_PROB = 0.35;
-var EPS4 = 1e-9;
+var EPS5 = 1e-9;
 function pitchClass9(value) {
   return (Math.trunc(value) % 12 + 12) % 12;
 }
@@ -1766,15 +1898,16 @@ function chordTonePcs(chord) {
   return pcs;
 }
 function fifthPcOf(chord) {
-  const hasFifth = chord.intervals.some((i) => pitchClass9(i) === 7);
-  return hasFifth ? pitchClass9(chord.rootPc + 7) : pitchClass9(chord.rootPc);
+  const fifths = new Set(chord.intervals.map((i) => pitchClass9(i)));
+  const chosen = fifths.has(7) ? 7 : fifths.has(6) ? 6 : fifths.has(8) ? 8 : void 0;
+  return chosen === void 0 ? pitchClass9(chord.rootPc) : pitchClass9(chord.rootPc + chosen);
 }
 function bassPcOf(chord) {
   return pitchClass9(chord.bassPc ?? chord.rootPc);
 }
 function beatPositions(start, end) {
   const positions = [];
-  for (let p = start; p < end - EPS4; p += 1) {
+  for (let p = start; p < end - EPS5; p += 1) {
     positions.push(p);
   }
   if (positions.length === 0) {
@@ -1794,7 +1927,7 @@ function buildRoot(ctx, seg) {
 function buildRootFifth(ctx, seg) {
   ctx.prevMidi = emit(ctx, seg.startBeat, bassPcOf(seg.chord));
   const mid = (seg.startBeat + seg.endBeat) / 2;
-  if (mid > seg.startBeat + EPS4 && mid < seg.endBeat - EPS4) {
+  if (mid > seg.startBeat + EPS5 && mid < seg.endBeat - EPS5) {
     ctx.prevMidi = emit(ctx, mid, fifthPcOf(seg.chord));
   }
 }
@@ -1809,7 +1942,7 @@ function buildPop(ctx, seg) {
     } else if (ctx.rng.prob(PICKUP_PROB)) {
       if (ctx.rng.prob(0.5)) {
         const base = placePc(rootPc, ctx.prevMidi, ctx.low);
-        emit(ctx, pos, rootPc, base - 12);
+        emit(ctx, pos, rootPc, Math.max(ctx.low, base - 12));
       } else {
         ctx.prevMidi = emit(ctx, pos, fifthPcOf(seg.chord));
       }
@@ -1905,7 +2038,7 @@ function generateBassLine(opts) {
     }
     const nextStart = ctx.notes[i + 1]?.startBeat ?? lastEnd;
     const durationBeat = nextStart - note.startBeat;
-    if (durationBeat <= EPS4) {
+    if (durationBeat <= EPS5) {
       continue;
     }
     out.push({
@@ -1941,18 +2074,22 @@ function scaleMatchesChord(chordPcs, scaleMask, scaleRootPc) {
   }
   return true;
 }
+var ALIASED_SCALE_NAMES = /* @__PURE__ */ new Set(["major", "naturalMinor"]);
+var HEPTATONIC_SIZE = 7;
 function chordScales(chord) {
   const chordPcs = chordPitchClasses(chord);
   const rootPc = pitchClass10(chord.rootPc);
   const ranked = [];
+  const seenMasks = /* @__PURE__ */ new Set();
   for (const name of Object.keys(NAMED_SCALES)) {
-    if (name === "chromatic") {
+    if (name === "chromatic" || ALIASED_SCALE_NAMES.has(name)) {
       continue;
     }
     const mask = NAMED_SCALES[name];
-    if (mask === void 0) {
+    if (mask === void 0 || seenMasks.has(mask)) {
       continue;
     }
+    seenMasks.add(mask);
     if (scaleMatchesChord(chordPcs, mask, rootPc)) {
       const size = popcount12(mask);
       ranked.push({ name, extra: size - chordPcs.length, size });
@@ -1964,7 +2101,11 @@ function chordScales(chord) {
     }
     return [];
   }
+  const preferHeptatonic = chordPcs.length <= 3;
   ranked.sort((a, b) => {
+    if (preferHeptatonic && a.size === HEPTATONIC_SIZE !== (b.size === HEPTATONIC_SIZE)) {
+      return a.size === HEPTATONIC_SIZE ? -1 : 1;
+    }
     if (a.extra !== b.extra) {
       return a.extra - b.extra;
     }
@@ -2116,7 +2257,7 @@ function scalesForChanges(chords) {
 
 // src/countermelody/index.ts
 var DEFAULT_TS2 = { numerator: 4, denominator: 4 };
-var EPS5 = 1e-9;
+var EPS6 = 1e-9;
 var GRID_STEP = 0.5;
 var MIN_ONSET_GAP = 1;
 var REGISTER_OFFSET = 12;
@@ -2127,12 +2268,12 @@ var REINFORCE_PROB = 0.35;
 var DEFAULT_MELODY_VELOCITY = 96;
 var VELOCITY_DROP = 16;
 function isWholeBeat(beat) {
-  return Math.abs(beat - Math.round(beat)) < EPS5;
+  return Math.abs(beat - Math.round(beat)) < EPS6;
 }
 function melodyNoteAt(melody, beat) {
   let found;
   for (const note of melody) {
-    if (note.startBeat - EPS5 <= beat && beat < note.startBeat + note.durationBeat - EPS5) {
+    if (note.startBeat - EPS6 <= beat && beat < note.startBeat + note.durationBeat - EPS6) {
       if (!found || note.startBeat > found.startBeat) {
         found = note;
       }
@@ -2141,7 +2282,7 @@ function melodyNoteAt(melody, beat) {
   return found;
 }
 function melodyAttacksAt(melody, beat) {
-  return melody.some((note) => Math.abs(note.startBeat - beat) < EPS5);
+  return melody.some((note) => Math.abs(note.startBeat - beat) < EPS6);
 }
 function followOnsets(melody) {
   return [...new Set(melody.map((note) => note.startBeat))].sort((a, b) => a - b);
@@ -2150,7 +2291,7 @@ function complementOnsets(melody, ts, spanStart, spanEnd, rng) {
   const onsets = [];
   const gridStart = Math.floor(spanStart / GRID_STEP) * GRID_STEP;
   let last = Number.NEGATIVE_INFINITY;
-  for (let beat = gridStart; beat < spanEnd - EPS5; beat += GRID_STEP) {
+  for (let beat = gridStart; beat < spanEnd - EPS6; beat += GRID_STEP) {
     const attacked = melodyAttacksAt(melody, beat);
     const sounding = melodyNoteAt(melody, beat) !== void 0;
     let place = false;
@@ -2161,7 +2302,7 @@ function complementOnsets(melody, ts, spanStart, spanEnd, rng) {
     } else if (isStrongBeat(beat, ts)) {
       place = rng.prob(REINFORCE_PROB);
     }
-    if (place && beat - last >= MIN_ONSET_GAP - EPS5) {
+    if (place && beat - last >= MIN_ONSET_GAP - EPS6) {
       onsets.push(beat);
       last = beat;
     }
@@ -2279,13 +2420,15 @@ function generateCounterMelody(opts) {
         if (register === "above" && candidate <= melPitch) {
           continue;
         }
-        if (prevPitch !== void 0 && melPrev !== void 0 && (createsParallelPerfect(prevPitch, candidate, melPrev, melPitch) || createsParallelOctave(prevPitch, candidate, melPrev, melPitch))) {
+        if (prevPitch !== void 0 && melPrev !== void 0 && // Parallel octaves are the perfect-class-zero case of this predicate,
+        // so a single check covers both parallel fifths and octaves.
+        createsParallelPerfect(prevPitch, candidate, melPrev, melPitch)) {
           continue;
         }
       }
       const score = scoreCandidate(candidate, melPitch, melPrev, prevPitch, chord, center);
-      const tie = Math.abs(score - bestScore) <= EPS5 && candidate < (bestPitch ?? Number.POSITIVE_INFINITY);
-      if (score > bestScore + EPS5 || tie) {
+      const tie = Math.abs(score - bestScore) <= EPS6 && candidate < (bestPitch ?? Number.POSITIVE_INFINITY);
+      if (score > bestScore + EPS6 || tie) {
         bestScore = score;
         bestPitch = candidate;
       }
@@ -2338,7 +2481,11 @@ var STYLE_MAP = {
   bossa: { style: "latin", feel: "straight", ghostBoost: false, snareBeat3: false },
   trap: { style: "trap", feel: "straight", ghostBoost: false, snareBeat3: true },
   halftime: { style: "sparse", feel: "straight", ghostBoost: false, snareBeat3: true },
-  breakbeat: { style: "rock", feel: "straight", ghostBoost: false, snareBeat3: false }
+  breakbeat: { style: "rock", feel: "straight", ghostBoost: false, snareBeat3: false },
+  // Four-on-the-floor dance kick with idol-style auxiliary percussion.
+  house: { style: "fourOnFloor", feel: "straight", ghostBoost: false, snareBeat3: false },
+  // Synth-pop pulse with denser 16th hi-hats and busy kick syncopation.
+  synthpop: { style: "synth", feel: "straight", ghostBoost: true, snareBeat3: false }
 };
 function mapStyle(style) {
   return STYLE_MAP[style];
@@ -2825,8 +2972,7 @@ function quantizeSwing(startBeat, swing, resolution) {
       return base + EIGHTH2 + DELTA_8 * clamped;
     }
     if (offset >= EIGHTH2 + HALF_16TH && offset < 3 * SIXTEENTH2 + HALF_16TH) {
-      const result = base + EIGHTH2 + DELTA_8 * clamped + SIXTEENTH2 + DELTA_16 * clamped;
-      return Math.min(result, base + 1 - 1 / 480);
+      return base + 3 * SIXTEENTH2 + DELTA_16 * clamped;
     }
     return startBeat;
   }
@@ -3021,6 +3167,52 @@ function generateHiHatForBeat(ctx, sec) {
   }
 }
 
+// src/drums/euclid.ts
+function euclideanRhythm(pulses, steps, rotation = 0) {
+  if (steps < 1) {
+    return [];
+  }
+  const p = Math.max(0, Math.min(pulses, steps));
+  const base = bjorklund(p, steps);
+  const shift = (rotation % steps + steps) % steps;
+  if (shift === 0) {
+    return base;
+  }
+  return base.map((_, i) => base[(i - shift + steps) % steps] ?? false);
+}
+function hasHit(mask, step) {
+  return (mask >> step & 1) === 1;
+}
+function patternToMask(pattern) {
+  let mask = 0;
+  for (let i = 0; i < pattern.length; i += 1) {
+    if (pattern[i]) {
+      mask |= 1 << i;
+    }
+  }
+  return mask;
+}
+function bjorklund(pulses, steps) {
+  if (pulses === 0) {
+    return Array.from({ length: steps }, () => false);
+  }
+  if (pulses >= steps) {
+    return Array.from({ length: steps }, () => true);
+  }
+  let head = Array.from({ length: pulses }, () => [true]);
+  let remainder = Array.from({ length: steps - pulses }, () => [false]);
+  while (remainder.length > 1) {
+    const count = Math.min(head.length, remainder.length);
+    const next = [];
+    for (let i = 0; i < count; i += 1) {
+      next.push([...head[i] ?? [], ...remainder[i] ?? []]);
+    }
+    remainder = head.length > count ? head.slice(count) : remainder.slice(count);
+    head = next;
+  }
+  return [...head.flat(), ...remainder.flat()];
+}
+
 // src/drums/fills.ts
 function getFillStartBeat(energy) {
   switch (energy) {
@@ -3037,6 +3229,9 @@ function selectFillType(from, to, style, nextEnergy, rng) {
   if (style === "sparse") {
     return rng.range(0, 1) === 0 ? "simpleCrash" : "breakdownFill";
   }
+  const toChorus = to === "chorus";
+  const fromIntro = from === "intro";
+  const highEnergy = style === "rock" || style === "fourOnFloor";
   if (nextEnergy === "low") {
     switch (rng.range(0, 2)) {
       case 0:
@@ -3047,25 +3242,10 @@ function selectFillType(from, to, style, nextEnergy, rng) {
         return "halfTimeFill";
     }
   }
-  if (nextEnergy === "peak") {
-    switch (rng.range(0, 3)) {
-      case 0:
-        return "tomDescend";
-      case 1:
-        return "snareRoll";
-      case 2:
-        return "linearFill";
-      default:
-        return "flamsAndDrags";
-    }
-  }
-  const toChorus = to === "chorus";
-  const fromIntro = from === "intro";
-  const highEnergy = style === "rock" || style === "fourOnFloor";
-  const choice = rng.range(0, 7);
   if (toChorus) {
+    const choice2 = rng.range(0, 7);
     if (highEnergy) {
-      switch (choice) {
+      switch (choice2) {
         case 0:
         case 1:
           return "tomDescend";
@@ -3083,7 +3263,7 @@ function selectFillType(from, to, style, nextEnergy, rng) {
           return "ghostToAccent";
       }
     }
-    switch (choice) {
+    switch (choice2) {
       case 0:
       case 1:
         return "snareTomCombo";
@@ -3100,7 +3280,7 @@ function selectFillType(from, to, style, nextEnergy, rng) {
     }
   }
   if (fromIntro) {
-    switch (choice) {
+    switch (rng.range(0, 5)) {
       case 0:
       case 1:
         return "snareRoll";
@@ -3114,6 +3294,7 @@ function selectFillType(from, to, style, nextEnergy, rng) {
         return "halfTimeFill";
     }
   }
+  const choice = rng.range(0, 7);
   if (highEnergy) {
     switch (choice) {
       case 0:
@@ -3296,6 +3477,10 @@ function generateFill(track, beatTick, beat, fillType, velocity) {
       if (beat === 2) {
         track.add(GM.SD, beatTick, 1, accentVel);
         track.add(GM.BD, beatTick, 1, fillVel);
+      } else if (beat === 3) {
+        track.add(GM.SD, beatTick, EIGHTH, accentVel);
+        track.add(GM.SD, beatTick + E, S, fillVel * 0.6);
+        track.add(GM.SD, beatTick + E + S, S, accentVel);
       }
       break;
   }
@@ -3338,6 +3523,19 @@ function isInPreChorusLift(section, bar, sectionBars, nextIsChorus) {
   }
   return bar >= sectionBars - 2;
 }
+function euclideanToKickPattern(mask) {
+  const slot = (step) => hasHit(mask, step) || hasHit(mask, (step + 15) % 16);
+  return {
+    beat1: slot(0),
+    beat1and: slot(2),
+    beat2: slot(4),
+    beat2and: slot(6),
+    beat3: slot(8),
+    beat3and: slot(10),
+    beat4: slot(12),
+    beat4and: slot(14)
+  };
+}
 function getKickPattern(section, style, bar, rng) {
   const p = { ...EMPTY };
   if (section === "outro") {
@@ -3542,6 +3740,17 @@ function generateDrums(opts) {
   const energy = sectionEnergy(section);
   const fillStartBeat = getFillStartBeat(energy);
   const percMood = percMoodCategory(style);
+  const nextSection = opts.nextSection ? mapSection(opts.nextSection) : section;
+  const nextEnergy = sectionEnergy(nextSection);
+  const euclidKick = opts.euclideanKick ? euclideanToKickPattern(
+    patternToMask(
+      euclideanRhythm(
+        opts.euclideanKick.pulses,
+        opts.euclideanKick.steps ?? 16,
+        opts.euclideanKick.rotation ?? 0
+      )
+    )
+  ) : void 0;
   const reuseSectionKick = (section === "b" || section === "chorus") && style !== "sparse";
   let sectionKick;
   for (let bar = 0; bar < opts.bars; bar += 1) {
@@ -3557,7 +3766,9 @@ function generateDrums(opts) {
       barHasOpenHh = !track.hasCrashNear(barStart + openHhBeatIndex);
     }
     let kick;
-    if (reuseSectionKick) {
+    if (euclidKick) {
+      kick = euclidKick;
+    } else if (reuseSectionKick) {
       sectionKick ??= getKickPattern(section, style, 0, rng);
       kick = sectionKick;
     } else {
@@ -3570,12 +3781,17 @@ function generateDrums(opts) {
       const velocity = calculateVelocity(section, beat);
       if (opts.fills && isLastBar && !inLift && beat >= fillStartBeat) {
         if (beat === fillStartBeat) {
-          currentFill = selectFillType(section, section, style, energy, rng);
+          currentFill = selectFillType(section, nextSection, style, nextEnergy, rng);
         }
         if (playMainVoices) {
+          const before = track.hits.length;
           generateFill(track, beatTick, beat, currentFill, velocity);
+          if (track.hits.length > before) {
+            continue;
+          }
+        } else {
+          continue;
         }
-        continue;
       }
       const ctx = {
         track,
@@ -3697,18 +3913,23 @@ function extractGrooveTemplate(events, ts, subdivision) {
   for (let i = 0; i < slotsPerBar; i += 1) {
     const count = counts[i] ?? 0;
     if (count === 0) {
-      slots.push({ timingOffset: 0, velocity: 0 });
+      slots.push({ timingOffset: 0, velocity: null });
       continue;
     }
     const velocityCount = velocityCounts[i] ?? 0;
     slots.push({
       timingOffset: (offsetSums[i] ?? 0) / count,
-      velocity: velocityCount > 0 ? (velocitySums[i] ?? 0) / velocityCount : 0
+      velocity: velocityCount > 0 ? (velocitySums[i] ?? 0) / velocityCount : null
     });
   }
-  return { subdivision, slotsPerBar, slots };
+  return { subdivision, slotsPerBar, slots, ts };
 }
 function applyGrooveTemplate(events, template, ts) {
+  if (template.ts && (template.ts.numerator !== ts.numerator || template.ts.denominator !== ts.denominator)) {
+    throw new Error(
+      `Groove template meter ${formatTimeSignature(template.ts)} does not match apply-time meter ${formatTimeSignature(ts)}`
+    );
+  }
   const barBeats = beatsPerBar(ts);
   return events.map((event) => {
     const { quantizedBeat, slotIndex } = quantizeToGrid(
@@ -3719,7 +3940,7 @@ function applyGrooveTemplate(events, template, ts) {
     );
     const slot = template.slots[slotIndex];
     const startBeat = quantizedBeat + (slot?.timingOffset ?? 0);
-    const velocity = slot && slot.velocity > 0 ? Math.round(slot.velocity) : event.velocity;
+    const velocity = slot && slot.velocity !== null && slot.velocity !== void 0 ? Math.round(slot.velocity) : event.velocity;
     return {
       pitch: event.pitch,
       startBeat,
@@ -3772,6 +3993,7 @@ var DEFAULT_METER = { numerator: 4, denominator: 4 };
 var COMFORT_LOW = 55;
 var COMFORT_HIGH = 79;
 var TESSITURA_WEIGHT = 1e-3;
+var TIE_BREAK_JITTER = 1e-6;
 function pitchClass11(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
@@ -3786,26 +4008,33 @@ function mulberry32(seed) {
   };
 }
 function inferKey(melody) {
-  let best = 0;
+  let best = majorKey(0);
   let bestScore = Number.NEGATIVE_INFINITY;
+  const candidates = [];
   for (let tonic = 0; tonic < 12; tonic += 1) {
-    const key = majorKey(tonic);
+    candidates.push(majorKey(tonic), minorKey(tonic));
+  }
+  for (const key of candidates) {
+    const tonic = pitchClass11(key.rootPc);
+    const isMinor = key.modeMask12 === NATURAL_MINOR_MASK;
+    const leadingTone = (tonic + 11) % 12;
     let score = 0;
     for (const n of melody) {
       const w = Math.max(0.25, n.durationBeat);
-      if (isScaleTone(n.pitch, key)) {
+      const pc = pitchClass11(n.pitch);
+      if (isScaleTone(n.pitch, key) || isMinor && pc === leadingTone) {
         score += w;
       }
-      if (pitchClass11(n.pitch) === tonic) {
+      if (pc === tonic) {
         score += 0.5 * w;
       }
     }
     if (score > bestScore) {
       bestScore = score;
-      best = tonic;
+      best = key;
     }
   }
-  return majorKey(best);
+  return best;
 }
 function buildCandidates(key, reharmonize) {
   const tones = scaleTonesInDegreeOrder(key);
@@ -3957,7 +4186,7 @@ function harmonizeMelody(opts) {
   const candidates = buildCandidates(key, opts.reharmonize);
   const candAt = (i) => candidates[i] ?? FALLBACK;
   const rng = mulberry32(opts.seed ?? 0);
-  const jitter = candidates.map(() => rng() * 1e-6);
+  const jitter = candidates.map(() => rng() * TIE_BREAK_JITTER);
   const melodyEnd = opts.melody.reduce((m, n) => Math.max(m, n.startBeat + n.durationBeat), 0);
   const hr = Math.max(0.25, opts.harmonicRhythm);
   const segCount = Math.max(1, Math.ceil(melodyEnd / hr));
@@ -4154,6 +4383,8 @@ function spelledInterval(a, b) {
     const reference = SIMPLE_REFERENCE[letterSteps + 1] ?? 0;
     if (reference - rawSemis > 6) {
       rawSemis += 12;
+    } else if (rawSemis - reference > 6) {
+      rawSemis -= 12;
     }
     semitones = rawSemis;
   }
@@ -4378,8 +4609,8 @@ function noteNames(notes) {
 }
 
 // src/symbol/index.ts
-var ROOT_RE = /^[A-G](?:#{1,2}|b{1,2})?/;
-var BASS_RE = /^[A-G](?:#{1,2}|b{1,2})?$/;
+var ROOT_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?/;
+var BASS_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?$/;
 var QUALITY_MAP = {
   "": "maj",
   m: "min",
@@ -4474,8 +4705,17 @@ var CANONICAL_SUFFIX = {
 function pitchClass12(value) {
   return (Math.trunc(value) % 12 + 12) % 12;
 }
-function bassPitchClass(token) {
-  return noteToPitchClass(parseNote(token));
+function makeSpelledChord(root, quality, bass) {
+  const chord = makeChord(
+    noteToPitchClass(root),
+    quality,
+    bass === void 0 ? void 0 : noteToPitchClass(bass)
+  );
+  chord.rootSpelling = { letter: root.letter, alter: root.alter };
+  if (bass !== void 0) {
+    chord.bassSpelling = { letter: bass.letter, alter: bass.alter };
+  }
+  return chord;
 }
 function parseChordSymbol(text) {
   const trimmed = text.trim();
@@ -4484,37 +4724,37 @@ function parseChordSymbol(text) {
     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 === void 0) {
-      throw new Error(`Unrecognized chord quality: ${text}`);
+  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 !== void 0 && 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 !== void 0 && BASS_RE.test(after)) {
-    return makeChord(rootPc, beforeQuality, bassPitchClass(after));
+  const quality = QUALITY_MAP[rest];
+  if (quality === void 0) {
+    throw new Error(`Unrecognized chord quality: ${text}`);
   }
-  const combinedQuality = QUALITY_MAP[rest];
-  if (combinedQuality !== void 0) {
-    return makeChord(rootPc, combinedQuality);
+  return makeSpelledChord(rootNote, quality);
+}
+function pitchClassName(pc, hint, flats) {
+  if (flats === void 0 && hint !== void 0 && 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 });
 }
 function formatChordSymbol(chord, opts) {
-  const spelling = opts?.flats ? "flat" : "sharp";
-  const rootNote = midiToNote(60 + pitchClass12(chord.rootPc), spelling);
-  const rootName = formatNote({ letter: rootNote.letter, alter: rootNote.alter });
+  const rootPc = pitchClass12(chord.rootPc);
+  const rootName = pitchClassName(rootPc, chord.rootSpelling, opts?.flats);
   const suffix = CANONICAL_SUFFIX[chord.quality];
   let symbol = `${rootName}${suffix}`;
-  if (chord.bassPc !== void 0 && pitchClass12(chord.bassPc) !== pitchClass12(chord.rootPc)) {
-    const bassNote = midiToNote(60 + pitchClass12(chord.bassPc), spelling);
-    symbol += `/${formatNote({ letter: bassNote.letter, alter: bassNote.alter })}`;
+  if (chord.bassPc !== void 0 && pitchClass12(chord.bassPc) !== rootPc) {
+    symbol += `/${pitchClassName(pitchClass12(chord.bassPc), chord.bassSpelling, opts?.flats)}`;
   }
   return symbol;
 }
@@ -4541,6 +4781,7 @@ var DERIVED_SPAN = 19;
 var VIOLATION_PENALTY = 1e3;
 var MISSING_TONE_PENALTY = 500;
 var POOR_DOUBLING_PENALTY = 4;
+var HIDDEN_PERFECT_PENALTY = 6;
 var MAX_CANDIDATES = 4e3;
 function pitchClass13(value) {
   return (Math.trunc(value) % 12 + 12) % 12;
@@ -4578,7 +4819,12 @@ function pitchesForPc(pc, range) {
       result.push(midi);
     }
   }
-  return result;
+  const center = (range.min + range.max) / 2;
+  return result.sort((a, b) => {
+    const da = Math.abs(a - center);
+    const db = Math.abs(b - center);
+    return da === db ? a - b : da - db;
+  });
 }
 function enumerateVoicings(chord, ranges, maxSpacing) {
   const chordPcs = chordPitchClasses(chord);
@@ -4654,9 +4900,6 @@ function violationCount(prev, cur, maxSpacing) {
       if (createsParallelPerfect(prevUpper, curUpper, prevLower, curLower)) {
         count += 1;
       }
-      if (createsParallelOctave(prevUpper, curUpper, prevLower, curLower)) {
-        count += 1;
-      }
       if (createsVoiceCrossing(curUpper, curLower)) {
         count += 1;
       }
@@ -4685,6 +4928,15 @@ function voiceLeadingCost(from, to) {
     }
     total += Math.abs(b - a);
   }
+  if (from.length >= 2) {
+    const bassPrev = from[0];
+    const bassCur = to[0];
+    const sopPrev = from[from.length - 1];
+    const sopCur = to[to.length - 1];
+    if (bassPrev !== void 0 && bassCur !== void 0 && sopPrev !== void 0 && sopCur !== void 0 && createsHiddenParallelPerfect(bassPrev, bassCur, sopPrev, sopCur)) {
+      total += HIDDEN_PERFECT_PENALTY;
+    }
+  }
   return total;
 }
 function voiceChord(chord, opts) {
@@ -4823,7 +5075,10 @@ function voiceChordStyled(chord, opts) {
   return stack.sort((a, b) => a - b);
 }
 function nextVoicing(current, chord, opts) {
-  const ranges = opts?.ranges !== void 0 || opts?.voices !== void 0 ? resolveRanges(opts) : current.map((pitch) => ({ min: pitch - 12, max: pitch + 12 }));
+  const ranges = opts?.ranges !== void 0 || opts?.voices !== void 0 ? resolveRanges(opts) : current.map((pitch) => {
+    const centre = Math.min(127, Math.max(0, pitch));
+    return { min: Math.max(0, centre - 12), max: Math.min(127, centre + 12) };
+  });
   const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
   const candidates = enumerateVoicings(chord, ranges, maxSpacing);
   let best;
@@ -4861,6 +5116,12 @@ function copyChord(data) {
   if (data.bassPc !== void 0) {
     copy.bassPc = data.bassPc;
   }
+  if (data.rootSpelling !== void 0) {
+    copy.rootSpelling = { letter: data.rootSpelling.letter, alter: data.rootSpelling.alter };
+  }
+  if (data.bassSpelling !== void 0) {
+    copy.bassSpelling = { letter: data.bassSpelling.letter, alter: data.bassSpelling.alter };
+  }
   return copy;
 }
 function spellPitchClassBare(pc, spelling) {
@@ -4946,12 +5207,16 @@ var Note = 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) {
+    if (semitones === 0) {
+      return new _Note(this.#data);
+    }
     if (this.#data.octave !== void 0) {
       return _Note.fromMidi(this.midi + semitones);
     }
@@ -4975,6 +5240,17 @@ var Note = class _Note {
   equals(other) {
     return this.#data.letter === other.#data.letter && this.#data.alter === other.#data.alter && 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() {
+    return this.data;
+  }
 };
 var Interval = class _Interval {
   #number;
@@ -5023,10 +5299,32 @@ var Interval = class _Interval {
   get name() {
     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() {
+    return { number: this.#number, quality: this.#quality, semitones: this.#semitones };
+  }
 };
 function resolveTonic(root, spelling) {
   return typeof root === "string" ? Note.of(root) : new Note(spellPitchClassBare(root, spelling));
 }
+function accidentalLoad(tonic, scale) {
+  return spellScale(tonic, scale).reduce((sum, note) => sum + Math.abs(note.alter), 0);
+}
+function bestTonicForScale(rootPc, scale) {
+  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);
+}
 var Key = class _Key {
   #scale;
   #tonic;
@@ -5043,24 +5341,34 @@ var Key = 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) {
-    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) {
-    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));
   }
   /**
    * A key on a named scale (e.g. `'dorian'`, `'harmonicMinor'`).
@@ -5187,6 +5495,19 @@ var Key = class _Key {
   contains(x) {
     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() {
+    return { scale: this.scale, tonic: this.#tonic.data };
+  }
 };
 var Chord = class _Chord {
   #data;
@@ -5383,13 +5704,17 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   negativeHarmony(key) {
-    return new _Chord(negativeHarmonyMirror(this.#data, this.#resolveKey(key).scale), this.#key);
+    const resolved = this.#resolveKey(key);
+    return new _Chord(negativeHarmonyMirror(this.#data, resolved.scale), key ?? this.#key);
   }
   /**
    * The n-th inversion: a copy whose bass is the chord tone `n` steps above the
    * 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.
@@ -5402,7 +5727,11 @@ var Chord = class _Chord {
     }
     const index = (n % length + length) % length;
     const data = copyChord(this.#data);
-    data.bassPc = mod125(this.#data.rootPc + (intervals[index] ?? 0));
+    if (index === 0) {
+      delete data.bassPc;
+    } else {
+      data.bassPc = mod125(this.#data.rootPc + (intervals[index] ?? 0));
+    }
     return new _Chord(data, this.#key);
   }
   /**
@@ -5583,6 +5912,21 @@ var Progression = class _Progression {
     const cadence = from !== void 0 && to !== void 0 ? detectCadence(from.data, to.data, resolved.scale) : null;
     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() {
+    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) {
     const resolved = key ?? this.#key;
@@ -5660,7 +6004,6 @@ function mulberry322(seed) {
 }
 function contourOffsets(contour, count) {
   const offsets = [];
-  const half = Math.floor(count / 2);
   for (let i = 0; i < count; i += 1) {
     switch (contour) {
       case "ascending":
@@ -5670,7 +6013,7 @@ function contourOffsets(contour, count) {
         offsets.push(-i);
         break;
       case "arch":
-        offsets.push(i <= half ? i : count - 1 - i);
+        offsets.push(Math.min(i, count - 1 - i));
         break;
       case "wave":
         offsets.push([0, 1, 0, -1][i % 4] ?? 0);
@@ -5686,11 +6029,15 @@ function generateMotif(opts) {
   const noteCount = Math.max(3, bars * 2);
   const beatsPerNote = totalBeats / noteCount;
   const rng = mulberry322(opts.seed ?? 0);
+  const jitterProb = Math.min(1, Math.max(0, opts.jitter ?? 0));
   const tonic = pitchClass14(opts.key.rootPc) + 60;
   const offsets = contourOffsets(contour, noteCount);
   const notes = [];
   for (let i = 0; i < noteCount; i += 1) {
-    const jitter = rng() < 0.25 ? 1 : 0;
+    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) {
@@ -6002,6 +6349,9 @@ function generateProgression(opts) {
   let preset;
   if (opts.presetId !== void 0) {
     preset = PRESETS.find((p) => p.id === opts.presetId);
+    if (preset === void 0) {
+      throw new Error(`Unknown progression preset: ${opts.presetId}`);
+    }
   }
   if (preset === void 0) {
     const pool = PRESETS.filter((p) => p.styles.includes(opts.style));
@@ -6072,15 +6422,17 @@ function generateRhythm(ts, opts = {}) {
   const seed = opts.seed ?? 0;
   const bars = opts.bars ?? DEFAULT_BARS;
   const subdivision = opts.subdivision ?? DEFAULT_SUBDIVISION;
-  const density = opts.density ?? DEFAULT_DENSITY;
-  const spanBeats = beatsPerBar(ts) * bars;
+  const density = Math.min(1, Math.max(0, opts.density ?? DEFAULT_DENSITY));
+  const barBeats = beatsPerBar(ts);
+  const spanBeats = barBeats * bars;
   const step = 1 / subdivision;
   const slotCount = Math.round(spanBeats * subdivision);
+  const slotsPerBar = Math.round(barBeats * subdivision);
   const rng = createRng(seed);
   const positions = [];
   for (let i = 0; i < slotCount; i += 1) {
     const position = i * step;
-    if (i === 0) {
+    if (i % slotsPerBar === 0) {
       positions.push(position);
       continue;
     }