@libraz/libcantus 0.9.2 → 0.9.3

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   BLUES_MASK: () => BLUES_MASK,
   CHROMATIC_MASK: () => CHROMATIC_MASK,
   Chord: () => Chord,
+  DEFAULT_GENERATION_BUDGET: () => DEFAULT_GENERATION_BUDGET,
   DORIAN_MASK: () => DORIAN_MASK,
   HARMONIC_MINOR_MASK: () => HARMONIC_MINOR_MASK,
   Interval: () => Interval,
@@ -52,6 +53,14 @@ __export(index_exports, {
   analyzeChord: () => analyzeChord,
   analyzeVoice: () => analyzeVoice,
   applyGrooveTemplate: () => applyGrooveTemplate,
+  assertFiniteNumber: () => assertFiniteNumber,
+  assertGenerationBudget: () => assertGenerationBudget,
+  assertInteger: () => assertInteger,
+  assertNoteEvent: () => assertNoteEvent,
+  assertNoteEvents: () => assertNoteEvents,
+  assertPositiveInt: () => assertPositiveInt,
+  assertRange: () => assertRange,
+  assertTimeSignature: () => assertTimeSignature,
   availableTensions: () => availableTensions,
   avoidNotes: () => avoidNotes,
   barPositionToBeat: () => barPositionToBeat,
@@ -70,6 +79,7 @@ __export(index_exports, {
   chordToRoman: () => chordToRoman,
   chordToneRole: () => chordToneRole,
   classifyInterval: () => classifyInterval,
+  createNoteEventIndex: () => createNoteEventIndex,
   createRng: () => createRng,
   createsHiddenParallelPerfect: () => createsHiddenParallelPerfect,
   createsParallelOctave: () => createsParallelOctave,
@@ -165,6 +175,86 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_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 assertRange(value, min, max, name) {
+  assertFiniteNumber(value, name);
+  if (value < min || value > max) {
+    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+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;
+}
+function assertTimeSignature(ts, name = "time signature") {
+  assertPositiveInt(ts.numerator, `${name}.numerator`);
+  assertPositiveInt(ts.denominator, `${name}.denominator`);
+  if (ts.grouping !== void 0) {
+    if (ts.grouping.length === 0) {
+      throw new RangeError(`${name}.grouping must not be empty`);
+    }
+    let sum = 0;
+    for (let index = 0; index < ts.grouping.length; index += 1) {
+      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);
+    }
+    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;
+    const pulses = compound ? ts.numerator / 3 : ts.numerator;
+    if (sum !== pulses) {
+      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);
+    }
+  }
+  return ts;
+}
+function assertNoteEvent(event, name = "note event", options = {}) {
+  assertFiniteNumber(event.pitch, `${name}.pitch`);
+  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);
+  assertRange(
+    event.durationBeat,
+    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    `${name}.durationBeat`
+  );
+  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {
+    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);
+  }
+  if (event.velocity !== void 0) {
+    assertRange(event.velocity, 0, 127, `${name}.velocity`);
+  }
+  return event;
+}
+function assertNoteEvents(events, name = "note events", options = {}) {
+  assertGenerationBudget(events.length, `${name} count`, options.budget);
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event !== void 0) {
+      assertNoteEvent(event, `${name}[${index}]`, options);
+    }
+  }
+  return events;
+}
+
 // src/core/meter/index.ts
 var EPS = 1e-9;
 function isMultiple(value, unit) {
@@ -181,21 +271,24 @@ function parseTimeSignature(text) {
   }
   const numerator = Number.parseInt(match[1] ?? "", 10);
   const denominator = Number.parseInt(match[2] ?? "", 10);
-  if (numerator <= 0 || denominator <= 0) {
+  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator) || numerator <= 0 || denominator <= 0) {
     throw new Error(`Invalid time signature: ${text}`);
   }
   return { numerator, denominator };
 }
 function formatTimeSignature(ts) {
+  assertTimeSignature(ts);
   return `${ts.numerator}/${ts.denominator}`;
 }
 function isCompound(ts) {
+  assertTimeSignature(ts);
   return ts.numerator % 3 === 0 && ts.numerator > 3;
 }
 function unitBeats(ts) {
   return 4 / ts.denominator;
 }
 function beatsPerBar(ts) {
+  assertTimeSignature(ts);
   return ts.numerator * unitBeats(ts);
 }
 function pulseBeats(ts) {
@@ -228,14 +321,19 @@ function isGroupHead(grouping, pulseIndex) {
   return false;
 }
 function beatToBarPosition(beatInQuarters, ts) {
+  assertFiniteNumber(beatInQuarters, "beat");
   const barLen = beatsPerBar(ts);
   const bar = Math.floor(beatInQuarters / barLen);
   return { bar, beat: beatInQuarters - bar * barLen };
 }
 function barPositionToBeat(pos, ts) {
+  assertInteger(pos.bar, "bar position bar");
+  assertFiniteNumber(pos.beat, "bar position beat");
   return pos.bar * beatsPerBar(ts) + pos.beat;
 }
 function metricWeight(beatInQuarters, ts) {
+  assertFiniteNumber(beatInQuarters, "beat");
+  assertTimeSignature(ts);
   const { beat } = beatToBarPosition(beatInQuarters, ts);
   const pulse = pulseBeats(ts);
   if (!isMultiple(beat, pulse)) {
@@ -264,9 +362,8 @@ function isStrongBeat(beatInQuarters, ts) {
   return metricWeight(beatInQuarters, ts) >= 2;
 }
 function tuplet(totalBeats, count) {
-  if (!Number.isInteger(count) || count <= 0) {
-    throw new Error(`Invalid tuplet count: ${count}`);
-  }
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, "tuplet total beats");
+  assertPositiveInt(count, "tuplet count");
   return new Array(count).fill(totalBeats / count);
 }
 
@@ -531,8 +628,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);
@@ -693,6 +792,31 @@ var ReasonFlag = /* @__PURE__ */ ((ReasonFlag2) => {
 })(ReasonFlag || {});
 var SUGGESTION_WINDOW = 12;
 var MAX_SUGGESTIONS = 3;
+var REASON_SEVERITY = [
+  [2 /* Tension */, 1 /* Warning */, 1 /* Warning */],
+  [4 /* AvoidNote */, 1 /* Warning */, 2 /* Dissonant */],
+  [8 /* ScaleTone */, 1 /* Warning */, 1 /* Warning */],
+  [16 /* NonScale */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [32 /* OutOfRange */, 1 /* Warning */, 1 /* Warning */],
+  [64 /* Tritone */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [128 /* LargeLeap */, 1 /* Warning */, 2 /* Dissonant */],
+  [1024 /* VerticalDissonance */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [2048 /* ParallelPerfect */, 1 /* Warning */, 2 /* Dissonant */],
+  [4096 /* HiddenParallel */, 1 /* Warning */, 2 /* Dissonant */],
+  [8192 /* VoiceCrossing */, 1 /* Warning */, 2 /* Dissonant */],
+  [16384 /* Suspension */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [32768 /* NeedsResolution */, 1 /* Warning */, 2 /* Dissonant */]
+];
+function minimumSafetyForReasons(reasons, profile) {
+  let minimum = 0 /* Safe */;
+  const severityIndex = profile === "strict" ? 2 : 1;
+  for (const entry of REASON_SEVERITY) {
+    if (reasons & entry[0]) {
+      minimum = Math.max(minimum, entry[severityIndex]);
+    }
+  }
+  return minimum;
+}
 function pitchClass4(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
@@ -717,8 +841,27 @@ function stepResolution(pitch, chord) {
   return void 0;
 }
 function evaluateSafety(q) {
+  assertSafetyContext(q);
+  assertFiniteNumber(q.candidatePitch, "candidatePitch");
   return evaluateInternal(q, true);
 }
+function assertSafetyContext(q) {
+  if (q.prevPitch !== void 0) assertFiniteNumber(q.prevPitch, "prevPitch");
+  if (q.vocalLow !== void 0) assertFiniteNumber(q.vocalLow, "vocalLow");
+  if (q.vocalHigh !== void 0) assertFiniteNumber(q.vocalHigh, "vocalHigh");
+  if (q.vocalLow !== void 0 && q.vocalHigh !== void 0 && q.vocalLow > q.vocalHigh) {
+    throw new RangeError("vocalLow must not exceed vocalHigh");
+  }
+  assertGenerationBudget(q.otherVoices.length, "other voices");
+  for (let index = 0; index < q.otherVoices.length; index += 1) {
+    const voice = q.otherVoices[index];
+    if (!voice) continue;
+    assertFiniteNumber(voice.pitch, `otherVoices[${index}].pitch`);
+    if (voice.prevPitch !== void 0) {
+      assertFiniteNumber(voice.prevPitch, `otherVoices[${index}].prevPitch`);
+    }
+  }
+}
 function evaluateInternal(q, collectSuggestions) {
   let reasons = 0;
   let level = 0 /* Safe */;
@@ -779,9 +922,11 @@ function evaluateInternal(q, collectSuggestions) {
     const pc = Math.abs(pitch - q.prevPitch) % 12;
     if (pc === 6) {
       reasons |= 64 /* Tritone */;
+      raise(2 /* Dissonant */);
     }
     if (isForbiddenMelodicLeap(q.prevPitch, pitch)) {
       reasons |= 128 /* LargeLeap */;
+      raise(parallelSeverity);
     }
     if (pc === 1) {
       reasons |= 256 /* MinorSecond */;
@@ -826,6 +971,7 @@ function evaluateInternal(q, collectSuggestions) {
       }
     }
   }
+  raise(minimumSafetyForReasons(reasons, q.profile));
   const result = { safety: level, reasons, rationale: describe(reasons, q) };
   if (resolveTo !== void 0) {
     result.resolveTo = resolveTo;
@@ -889,11 +1035,15 @@ function describe(reasons, q) {
   return q.chord ? "Placeable" : "No chord context";
 }
 function enumerateSafePitches(q, pitchLow, pitchHigh) {
+  assertSafetyContext(q);
   const chordTones = [];
   const others = [];
-  if (!Number.isFinite(pitchLow) || !Number.isFinite(pitchHigh)) {
-    return [];
+  assertInteger(pitchLow, "pitchLow");
+  assertInteger(pitchHigh, "pitchHigh");
+  if (pitchLow > pitchHigh) {
+    throw new RangeError(`pitchLow must not exceed pitchHigh; received ${pitchLow} > ${pitchHigh}`);
   }
+  assertGenerationBudget(pitchHigh - pitchLow + 1, "safe pitch candidates");
   for (let pitch = pitchHigh; pitch >= pitchLow; pitch -= 1) {
     const result = evaluateInternal({ ...q, candidatePitch: pitch }, false);
     if (result.safety === 2 /* Dissonant */) {
@@ -1037,11 +1187,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}`);
   }
@@ -1290,6 +1445,73 @@ function detectCadence(from, to, key) {
   return null;
 }
 
+// src/core/event-index/index.ts
+var EPS2 = 1e-9;
+function upperBound(values, beat) {
+  let low = 0;
+  let high = values.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if ((values[middle]?.note.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+function createNoteEventIndex(events, options = {}) {
+  assertNoteEvents(events, "note events", options);
+  const notes = events.map((note, originalIndex) => ({
+    note,
+    originalIndex,
+    endBeat: note.startBeat + note.durationBeat
+  })).sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex);
+  const prefixMaxEnd = [];
+  let maxEnd = Number.NEGATIVE_INFINITY;
+  for (const indexed of notes) {
+    maxEnd = Math.max(maxEnd, indexed.endBeat);
+    prefixMaxEnd.push(maxEnd);
+  }
+  return {
+    notes,
+    at(beat) {
+      let index = upperBound(notes, beat + EPS2) - 1;
+      while (index >= 0) {
+        if ((prefixMaxEnd[index] ?? Number.NEGATIVE_INFINITY) <= beat + EPS2) {
+          return void 0;
+        }
+        const indexed = notes[index];
+        if (indexed && indexed.note.durationBeat > 0 && indexed.note.startBeat - EPS2 <= beat && beat < indexed.endBeat - EPS2) {
+          return indexed;
+        }
+        index -= 1;
+      }
+      return void 0;
+    },
+    attacksAt(beat) {
+      const firstAfter = upperBound(notes, beat + EPS2);
+      const candidate = notes[firstAfter - 1];
+      return candidate !== void 0 && Math.abs(candidate.note.startBeat - beat) < EPS2;
+    },
+    onsetsBetween(startBeat, endBeat) {
+      const result = [];
+      let index = upperBound(notes, startBeat + EPS2);
+      while (index < notes.length) {
+        const onset = notes[index]?.note.startBeat;
+        if (onset === void 0 || onset >= endBeat - EPS2) {
+          break;
+        }
+        if (result[result.length - 1] !== onset) {
+          result.push(onset);
+        }
+        index += 1;
+      }
+      return result;
+    }
+  };
+}
+
 // src/analyze/detect/index.ts
 function pitchClass5(value) {
   return (Math.trunc(value) % 12 + 12) % 12;
@@ -1297,12 +1519,21 @@ function pitchClass5(value) {
 function uniquePitchClasses(pitches) {
   return [...new Set(pitches.map(pitchClass5))].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 = pitchClass5(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 ? pitchClass5(opts.bassPc) : inputKind === "midi" ? pitchClass5(pitches.reduce((lowest, pitch) => Math.min(lowest, pitch), Infinity)) : void 0;
   const inputSet = new Set(input);
   const matches = [];
   const qualities = chordQualities();
@@ -1317,8 +1548,8 @@ function detectChord(pitches) {
         continue;
       }
       const extraPcs = input.filter((pc) => !toneSet.has(pc));
-      const bassIndex = chord.intervals.findIndex((iv) => pitchClass5(rootPc + iv) === bassPc);
-      const inversion = bassIndex > 0 ? bassIndex : 0;
+      const bassIndex = bassPc === void 0 ? -1 : chord.intervals.findIndex((iv) => pitchClass5(rootPc + iv) === bassPc);
+      const inversion = bassPc === void 0 ? null : bassIndex > 0 ? bassIndex : 0;
       const match = {
         rootPc,
         quality,
@@ -1327,7 +1558,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);
@@ -1349,8 +1580,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;
   }
@@ -1358,6 +1589,7 @@ function detectChordBest(pitches) {
 }
 var MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MINOR_MASK];
 function detectKey(pitches) {
+  assertPitches(pitches);
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];
@@ -1409,10 +1641,21 @@ function detectKey(pitches) {
 
 // src/analyze/timeline/index.ts
 function chordTimelineFromChords(chords, totalBeats) {
-  const sorted = [...chords].sort((a, b) => a.startBeat - b.startBeat);
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, "timeline totalBeats");
+  assertGenerationBudget(chords.length, "timeline chords");
+  for (let index = 0; index < chords.length; index += 1) {
+    assertRange(
+      chords[index]?.startBeat ?? Number.NaN,
+      0,
+      Number.MAX_SAFE_INTEGER,
+      `chords[${index}].startBeat`
+    );
+  }
+  const sorted = [...chords].filter((chord) => chord.startBeat < totalBeats).sort((a, b) => a.startBeat - b.startBeat);
   const segments = sorted.map((gc, i) => {
     const next = sorted[i + 1];
-    const endBeat = Math.max(gc.startBeat, next ? next.startBeat : totalBeats);
+    const nextBeat = next ? next.startBeat : totalBeats;
+    const endBeat = Math.min(totalBeats, Math.max(gc.startBeat, nextBeat));
     return {
       startBeat: gc.startBeat,
       endBeat,
@@ -1423,6 +1666,7 @@ function chordTimelineFromChords(chords, totalBeats) {
 }
 function segmentLookup(segments) {
   return (beat) => {
+    assertFiniteNumber(beat, "timeline query beat");
     for (const seg of segments) {
       if (beat >= seg.startBeat && beat < seg.endBeat) {
         return seg.chord;
@@ -1431,7 +1675,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;
@@ -1473,11 +1717,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 = pitchClass6(note.pitch);
     weights[pc] = (weights[pc] ?? 0) + overlap * velocityFactor * accent;
@@ -1491,7 +1735,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);
@@ -1524,26 +1768,40 @@ function sameChord(a, b) {
 }
 function chordTimelineFromNotes(notes, opts = {}) {
   const ts = opts.ts ?? parseTimeSignature("4/4");
+  assertTimeSignature(ts);
   const harmonicRhythm = opts.harmonicRhythm ?? beatsPerBar(ts);
-  if (!(harmonicRhythm > 0)) {
-    throw new Error(`Invalid harmonic rhythm: ${harmonicRhythm}`);
-  }
-  const sounding = notes.filter((note) => note.durationBeat > 0);
+  assertRange(harmonicRhythm, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "harmonic rhythm");
+  assertNoteEvents(notes, "timeline notes", { allowNonPositiveDuration: true });
+  const soundingIndex = createNoteEventIndex(notes.filter((note) => note.durationBeat > 0));
+  const sounding = soundingIndex.notes.map(({ note }) => note);
   const lastNoteEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
   const totalBeats = opts.totalBeats ?? lastNoteEnd;
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, "timeline totalBeats");
   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));
+  assertGenerationBudget(windowCount, "timeline windows");
+  const windowNotes = Array.from({ length: windowCount }, () => []);
+  let memberships = 0;
+  for (const indexed of soundingIndex.notes) {
+    const first = Math.max(0, Math.floor(indexed.note.startBeat / harmonicRhythm));
+    const lastExclusive = Math.min(windowCount, Math.ceil(indexed.endBeat / harmonicRhythm));
+    memberships += Math.max(0, lastExclusive - first);
+    assertGenerationBudget(memberships, "timeline note-to-window memberships");
+    for (let window = first; window < lastExclusive; window += 1) {
+      windowNotes[window]?.push(indexed.note);
+    }
+  }
   for (let i = 0; i < windowCount; i += 1) {
     const start = i * harmonicRhythm;
     const end = Math.min(start + harmonicRhythm, totalBeats);
-    const inferred = analyzeWindow(sounding, start, end, ts, key);
+    const inferred = analyzeWindow(windowNotes[i] ?? [], 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;
@@ -1568,7 +1826,7 @@ function detectCadences(timeline, key) {
     if (!prev || !cur) {
       continue;
     }
-    if (Math.abs(cur.startBeat - prev.endBeat) > EPS2) {
+    if (Math.abs(cur.startBeat - prev.endBeat) > EPS3) {
       continue;
     }
     const type = detectCadence(prev.chord, cur.chord, key);
@@ -1580,9 +1838,9 @@ function detectCadences(timeline, key) {
 }
 
 // src/analyze/arrange/internal.ts
-var EPS3 = 1e-9;
+var EPS4 = 1e-9;
 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 = [];
@@ -1600,7 +1858,7 @@ function splitIntoSubVoices(ordered) {
   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 + EPS3;
+      return last !== void 0 && last.startBeat + last.durationBeat <= note.startBeat + EPS4;
     });
     if (lane) {
       lane.push(note);
@@ -1618,9 +1876,11 @@ function prepareTracks(tracks) {
       voice,
       sounding: voice.map((note, i) => {
         const prev = i > 0 ? voice[i - 1] : void 0;
+        const prevEnd = prev === void 0 ? void 0 : prev.startBeat + prev.durationBeat;
+        const contiguous = prevEnd !== void 0 && Math.abs(prevEnd - note.startBeat) <= EPS4;
         return {
           pitch: note.pitch,
-          prevPitch: prev?.pitch,
+          prevPitch: contiguous ? prev?.pitch : void 0,
           startBeat: note.startBeat,
           endBeat: note.startBeat + note.durationBeat
         };
@@ -1652,11 +1912,16 @@ function clamp01(value) {
 }
 function tensionCurve(tracks, opts = {}) {
   const ts = opts.ts ?? parseTimeSignature("4/4");
+  assertTimeSignature(ts);
+  assertGenerationBudget(tracks.length, "arrangement tracks");
+  for (let index = 0; index < tracks.length; index += 1) {
+    assertNoteEvents(tracks[index]?.notes ?? [], `tracks[${index}].notes`, {
+      allowNonPositiveDuration: true
+    });
+  }
   const profile = opts.profile ?? "pop";
   const step = opts.step ?? 1;
-  if (!(step > 0)) {
-    throw new Error(`Invalid tension sampling step: ${step}`);
-  }
+  assertRange(step, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "tension sampling step");
   const pooled = poolNotes(tracks);
   const totalBeats = pooled.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
   const { timeline, key } = chordTimelineFromNotes(pooled, {
@@ -1666,7 +1931,8 @@ 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));
+  assertGenerationBudget(sampleCount, "tension samples");
   for (let i = 0; i < sampleCount; i += 1) {
     const beat = i * step;
     points.push({ beat, tension: sampleTension(prepared, timeline, key, ts, profile, beat) });
@@ -1736,7 +2002,7 @@ function sampleTension(prepared, timeline, key, ts, profile, beat) {
 }
 
 // src/analyze/voice/index.ts
-var EPS4 = 1e-9;
+var EPS5 = 1e-9;
 function pitchClass8(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
@@ -1792,6 +2058,7 @@ function stepResolution2(pitch, chord) {
   return void 0;
 }
 function analyzeVoice(voice, chordAtBeat, key, otherVoicesAtBeat) {
+  assertNoteEvents(voice, "voice notes", { allowNonPositiveDuration: true });
   const result = [];
   for (let i = 0; i < voice.length; i += 1) {
     const note = voice[i];
@@ -1800,8 +2067,10 @@ function analyzeVoice(voice, chordAtBeat, key, otherVoicesAtBeat) {
     }
     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 - EPS4 ? prevNote : void 0;
-    const next = nextNote !== void 0 && nextNote.startBeat > note.startBeat + EPS4 ? nextNote : void 0;
+    const prevEnd = prevNote === void 0 ? Number.NEGATIVE_INFINITY : prevNote.startBeat + prevNote.durationBeat;
+    const noteEnd = note.startBeat + note.durationBeat;
+    const prev = prevNote !== void 0 && Math.abs(prevEnd - note.startBeat) <= EPS5 ? prevNote : void 0;
+    const next = nextNote !== void 0 && Math.abs(noteEnd - nextNote.startBeat) <= EPS5 ? nextNote : void 0;
     const chord = chordAtBeat(note.startBeat);
     const labels = [];
     const member = isChordMember2(note.pitch, chord);
@@ -1941,8 +2210,9 @@ function otherVoicesSounding(prepared, excludeTrack, excludeVoice, beat) {
           continue;
         }
         const snap = { pitch: note.pitch };
-        if (note.prevPitch !== void 0) {
-          snap.prevPitch = note.prevPitch;
+        const previous = Math.abs(note.startBeat - beat) <= EPS4 ? note.prevPitch : note.pitch;
+        if (previous !== void 0) {
+          snap.prevPitch = previous;
         }
         out.push(snap);
       }
@@ -1954,7 +2224,7 @@ 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 + EPS3 && segment.startBeat < noteEnd - EPS3) {
+    if (segment.startBeat > note.startBeat + EPS4 && segment.startBeat < noteEnd - EPS4) {
       beats.push(segment.startBeat);
     }
   }
@@ -1962,6 +2232,13 @@ function evaluationBeats(note, timeline) {
 }
 function analyzeArrangement(tracks, opts = {}) {
   const ts = opts.ts ?? parseTimeSignature("4/4");
+  assertTimeSignature(ts);
+  assertGenerationBudget(tracks.length, "arrangement tracks");
+  for (let index = 0; index < tracks.length; index += 1) {
+    assertNoteEvents(tracks[index]?.notes ?? [], `tracks[${index}].notes`, {
+      allowNonPositiveDuration: true
+    });
+  }
   const profile = opts.profile ?? "pop";
   const pooled = poolNotes(tracks);
   const { timeline, key, segmentConfidence } = chordTimelineFromNotes(pooled, {
@@ -1992,11 +2269,18 @@ function analyzeArrangement(tracks, opts = {}) {
           (beat) => otherVoicesSounding(prepared, t, v, beat)
         )
       );
-      for (const note of subVoice.voice) {
+      for (let noteIndex = 0; noteIndex < subVoice.voice.length; noteIndex += 1) {
+        const note = subVoice.voice[noteIndex];
+        const preparedNote = subVoice.sounding[noteIndex];
+        if (note === void 0 || preparedNote === void 0) {
+          continue;
+        }
         for (const beat of evaluationBeats(note, timeline)) {
+          const atOnset = Math.abs(beat - note.startBeat) <= EPS4;
           const result = evaluateSafety({
             profile,
             candidatePitch: note.pitch,
+            prevPitch: atOnset ? preparedNote.prevPitch : note.pitch,
             chord: timeline.at(beat),
             key,
             otherVoices: otherVoicesSounding(prepared, t, v, beat),
@@ -2013,6 +2297,12 @@ function analyzeArrangement(tracks, opts = {}) {
             if (result.rationale !== void 0) {
               conflict.rationale = result.rationale;
             }
+            if (result.resolveTo !== void 0) {
+              conflict.resolveTo = result.resolveTo;
+            }
+            if (result.suggestions !== void 0) {
+              conflict.suggestions = [...result.suggestions];
+            }
             conflicts.push(conflict);
           }
         }
@@ -2170,6 +2460,7 @@ function spelledInterval(a, b) {
 
 // src/core/random/index.ts
 function createRng(seed) {
+  assertFiniteNumber(seed, "seed");
   let state = seed >>> 0;
   const next = () => {
     state = state + 1831565813 >>> 0;
@@ -2180,31 +2471,71 @@ function createRng(seed) {
   };
   return {
     next,
-    prob: (p) => next() < p,
-    range: (lo, hi) => lo + Math.floor(next() * (hi - lo + 1)),
-    float: (lo, hi) => lo + next() * (hi - lo)
+    prob: (p) => next() < assertRange(p, 0, 1, "probability"),
+    range: (lo, hi) => {
+      assertInteger(lo, "range lower bound");
+      assertInteger(hi, "range upper bound");
+      if (lo > hi) {
+        throw new RangeError(
+          `range lower bound must not exceed upper bound; received ${lo} > ${hi}`
+        );
+      }
+      assertInteger(hi - lo, "range span", 0);
+      return lo + Math.floor(next() * (hi - lo + 1));
+    },
+    float: (lo, hi) => {
+      assertFiniteNumber(lo, "float lower bound");
+      assertFiniteNumber(hi, "float upper bound");
+      if (lo > hi) {
+        throw new RangeError(
+          `float lower bound must not exceed upper bound; received ${lo} > ${hi}`
+        );
+      }
+      assertFiniteNumber(hi - lo, "float span");
+      return lo + next() * (hi - lo);
+    }
   };
 }
 
 // src/core/tuning/index.ts
 var TWELVE_TET = { refStep: 69, refFreq: 440, divisions: 12 };
+function assertTuning(tuning) {
+  assertFiniteNumber(tuning.refStep, "tuning.refStep");
+  assertRange(tuning.refFreq, Number.MIN_VALUE, Number.MAX_VALUE, "tuning.refFreq");
+  assertPositiveInt(tuning.divisions, "tuning.divisions");
+  return tuning;
+}
 function edo(n, refFreq = 440, refStep = 69) {
+  assertPositiveInt(n, "EDO divisions");
+  assertRange(refFreq, Number.MIN_VALUE, Number.MAX_VALUE, "reference frequency");
+  assertFiniteNumber(refStep, "reference step");
   return { refStep, refFreq, divisions: n };
 }
 function frequencyOf(step, tuning = TWELVE_TET) {
-  return tuning.refFreq * 2 ** ((step - tuning.refStep) / tuning.divisions);
+  assertFiniteNumber(step, "step");
+  assertTuning(tuning);
+  const result = tuning.refFreq * 2 ** ((step - tuning.refStep) / tuning.divisions);
+  return assertRange(result, Number.MIN_VALUE, Number.MAX_VALUE, "frequency result");
 }
 function nearestStep(freq, tuning = TWELVE_TET) {
+  assertRange(freq, Number.MIN_VALUE, Number.MAX_VALUE, "frequency");
+  assertTuning(tuning);
   return Math.round(tuning.refStep + tuning.divisions * Math.log2(freq / tuning.refFreq));
 }
 function centsBetweenFreq(a, b) {
-  return 1200 * Math.log2(b / a);
+  assertRange(a, Number.MIN_VALUE, Number.MAX_VALUE, "first frequency");
+  assertRange(b, Number.MIN_VALUE, Number.MAX_VALUE, "second frequency");
+  return 1200 * (Math.log2(b) - Math.log2(a));
 }
 function centsOfSteps(steps, tuning = TWELVE_TET) {
-  return steps * 1200 / tuning.divisions;
+  assertFiniteNumber(steps, "steps");
+  assertTuning(tuning);
+  return assertFiniteNumber(steps * 1200 / tuning.divisions, "cents result");
 }
 function ratioToCents(numerator, denominator) {
-  return 1200 * Math.log2(numerator / denominator);
+  assertRange(numerator, Number.MIN_VALUE, Number.MAX_VALUE, "ratio numerator");
+  assertRange(denominator, Number.MIN_VALUE, Number.MAX_VALUE, "ratio denominator");
+  return 1200 * (Math.log2(numerator) - Math.log2(denominator));
 }
 var JUST_RATIOS = {
   0: [1, 1],
@@ -2222,9 +2553,10 @@ var JUST_RATIOS = {
   12: [2, 1]
 };
 function justDeviationCents(semitoneClass) {
+  assertInteger(semitoneClass, "semitone class", 0, 12);
   const ratio = JUST_RATIOS[semitoneClass];
   if (!ratio) {
-    return Number.NaN;
+    throw new RangeError(`semitone class has no just ratio: ${semitoneClass}`);
   }
   return ratioToCents(ratio[0], ratio[1]) - semitoneClass * 100;
 }
@@ -2236,7 +2568,7 @@ var DEFAULT_OCTAVE = 2;
 var STRONG_VELOCITY = 100;
 var WEAK_VELOCITY = 80;
 var PICKUP_PROB = 0.35;
-var EPS5 = 1e-9;
+var EPS6 = 1e-9;
 function pitchClass9(value) {
   return (Math.trunc(value) % 12 + 12) % 12;
 }
@@ -2276,7 +2608,7 @@ function bassPcOf(chord) {
 }
 function beatPositions(start, end) {
   const positions = [];
-  for (let p = start; p < end - EPS5; p += 1) {
+  for (let p = start; p < end - EPS6; p += 1) {
     positions.push(p);
   }
   if (positions.length === 0) {
@@ -2296,7 +2628,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 + EPS5 && mid < seg.endBeat - EPS5) {
+  if (mid > seg.startBeat + EPS6 && mid < seg.endBeat - EPS6) {
     ctx.prevMidi = emit(ctx, mid, fifthPcOf(seg.chord));
   }
 }
@@ -2358,13 +2690,30 @@ function buildWalking(ctx, seg, next) {
   });
 }
 function generateBassLine(opts) {
+  assertGenerationBudget(opts.segments.length, "bass segments");
+  for (let index = 0; index < opts.segments.length; index += 1) {
+    const segment = opts.segments[index];
+    if (!segment) continue;
+    assertRange(segment.startBeat, 0, Number.MAX_SAFE_INTEGER, `segments[${index}].startBeat`);
+    assertRange(segment.endBeat, 0, Number.MAX_SAFE_INTEGER, `segments[${index}].endBeat`);
+    if (segment.endBeat <= segment.startBeat) {
+      throw new RangeError(`segments[${index}] must have a positive duration`);
+    }
+  }
   const segments = [...opts.segments].sort((a, b) => a.startBeat - b.startBeat);
   if (segments.length === 0) {
     return [];
   }
   const ts = opts.ts ?? DEFAULT_TS;
+  assertTimeSignature(ts);
   const style = opts.style ?? DEFAULT_STYLE;
   const octave = opts.octave ?? DEFAULT_OCTAVE;
+  assertInteger(octave, "bass octave", -1, 9);
+  const estimatedNotes = segments.reduce(
+    (count, segment) => count + Math.max(1, Math.ceil(segment.endBeat - segment.startBeat)),
+    0
+  );
+  assertGenerationBudget(estimatedNotes, "bass notes");
   const low = octave * 12 + 12;
   const ctx = {
     ts,
@@ -2407,7 +2756,7 @@ function generateBassLine(opts) {
     }
     const nextStart = ctx.notes[i + 1]?.startBeat ?? lastEnd;
     const durationBeat = nextStart - note.startBeat;
-    if (durationBeat <= EPS5) {
+    if (durationBeat <= EPS6) {
       continue;
     }
     out.push({
@@ -2422,7 +2771,7 @@ function generateBassLine(opts) {
 
 // src/generate/countermelody/index.ts
 var DEFAULT_TS2 = { numerator: 4, denominator: 4 };
-var EPS6 = 1e-9;
+var EPS7 = 1e-9;
 var GRID_STEP = 0.5;
 var MIN_ONSET_GAP = 1;
 var REGISTER_OFFSET = 12;
@@ -2433,30 +2782,35 @@ var REINFORCE_PROB = 0.35;
 var DEFAULT_MELODY_VELOCITY = 96;
 var VELOCITY_DROP = 16;
 function isWholeBeat(beat) {
-  return Math.abs(beat - Math.round(beat)) < EPS6;
+  return Math.abs(beat - Math.round(beat)) < EPS7;
 }
 function melodyNoteAt(melody, beat) {
-  let found;
-  for (const note of melody) {
-    if (note.startBeat - EPS6 <= beat && beat < note.startBeat + note.durationBeat - EPS6) {
-      if (!found || note.startBeat > found.startBeat) {
-        found = note;
-      }
-    }
-  }
-  return found;
+  return melody.at(beat)?.note;
 }
 function melodyAttacksAt(melody, beat) {
-  return melody.some((note) => Math.abs(note.startBeat - beat) < EPS6);
+  return melody.attacksAt(beat);
+}
+function melodySnapshotAt(melody, beat) {
+  const current = melodyNoteAt(melody, beat);
+  if (current === void 0) {
+    return void 0;
+  }
+  const attacked = Math.abs(current.startBeat - beat) < EPS7;
+  const previous = attacked ? melodyNoteAt(melody, beat - EPS7 * 2) : current;
+  const snapshot = { pitch: current.pitch };
+  if (previous !== void 0) {
+    snapshot.prevPitch = previous.pitch;
+  }
+  return snapshot;
 }
 function followOnsets(melody) {
-  return [...new Set(melody.map((note) => note.startBeat))].sort((a, b) => a - b);
+  return [...new Set(melody.notes.map(({ note }) => note.startBeat))];
 }
 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 - EPS6; beat += GRID_STEP) {
+  for (let beat = gridStart; beat < spanEnd - EPS7; beat += GRID_STEP) {
     const attacked = melodyAttacksAt(melody, beat);
     const sounding = melodyNoteAt(melody, beat) !== void 0;
     let place = false;
@@ -2467,7 +2821,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 - EPS6) {
+    if (place && beat - last >= MIN_ONSET_GAP - EPS7) {
       onsets.push(beat);
       last = beat;
     }
@@ -2513,54 +2867,102 @@ function scoreCandidate(pitch, melPitch, melPrev, prevPitch, chord, center) {
   score -= Math.abs(pitch - center) * 0.02;
   return score;
 }
-function fallbackPitch(melPitch, prevPitch, center, register, low, high, key) {
-  let target = prevPitch ?? Math.round(center);
-  if (melPitch !== void 0) {
-    if (register === "below" && target >= melPitch) {
-      target = melPitch - 5;
-    } else if (register === "above" && target <= melPitch) {
-      target = melPitch + 5;
+function heldNoteBoundaries(melody, startBeat, endBeat, chordChangeBeats) {
+  const boundaries = /* @__PURE__ */ new Set([startBeat]);
+  for (const onset of melody.onsetsBetween(startBeat, endBeat)) {
+    boundaries.add(onset);
+  }
+  for (const beat of chordChangeBeats) {
+    if (beat > startBeat + EPS7 && beat < endBeat - EPS7) {
+      boundaries.add(beat);
     }
   }
-  target = Math.min(Math.max(target, low), high);
-  let pitch = nearestScaleTone(target, key);
-  if (melPitch !== void 0) {
-    while (register === "below" && pitch >= melPitch && pitch - 12 >= low) {
-      pitch -= 12;
+  const firstGrid = Math.floor(startBeat / GRID_STEP + 1) * GRID_STEP;
+  for (let beat = firstGrid; beat < endBeat - EPS7; beat += GRID_STEP) {
+    boundaries.add(beat);
+  }
+  return [...boundaries].sort((a, b) => a - b);
+}
+function heldPitchSafety(pitch, startBeat, endBeat, prevPitch, melody, opts, profile, register, low, high, ts) {
+  let worst = 0 /* Safe */;
+  const boundaries = heldNoteBoundaries(melody, startBeat, endBeat, opts.chordChangeBeats ?? []);
+  for (const boundary of boundaries) {
+    const melodyVoice = melodySnapshotAt(melody, boundary);
+    if (melodyVoice !== void 0 && (register === "below" && pitch >= melodyVoice.pitch || register === "above" && pitch <= melodyVoice.pitch)) {
+      return null;
     }
-    while (register === "above" && pitch <= melPitch && pitch + 12 <= high) {
-      pitch += 12;
+    const atCounterOnset = Math.abs(boundary - startBeat) < EPS7;
+    const result = evaluateSafety({
+      profile,
+      candidatePitch: pitch,
+      prevPitch: atCounterOnset ? prevPitch : pitch,
+      chord: opts.chordAt(boundary),
+      key: opts.key,
+      otherVoices: melodyVoice ? [melodyVoice] : [],
+      strongBeat: isStrongBeat(boundary, ts),
+      vocalLow: low,
+      vocalHigh: high
+    });
+    worst = Math.max(worst, result.safety);
+    if (worst === 2 /* Dissonant */) {
+      return worst;
     }
   }
-  return Math.min(Math.max(pitch, low), high);
+  return worst;
 }
 function generateCounterMelody(opts) {
-  const melody = [...opts.melody].sort((a, b) => a.startBeat - b.startBeat);
-  if (melody.length === 0) {
+  const melody = createNoteEventIndex(opts.melody);
+  if (melody.notes.length === 0) {
     return [];
   }
   const ts = opts.ts ?? DEFAULT_TS2;
+  assertTimeSignature(ts);
   const register = opts.register ?? "below";
   const rhythm = opts.rhythm ?? "complement";
   const profile = opts.profile ?? "pop";
   const rng = createRng(opts.seed ?? 0);
-  const spanStart = melody[0]?.startBeat ?? 0;
-  const spanEnd = melody.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), spanStart);
-  const meanPitch = melody.reduce((sum, n) => sum + n.pitch, 0) / melody.length;
+  const spanStart = melody.notes[0]?.note.startBeat ?? 0;
+  const spanEnd = melody.notes.reduce((end, n) => Math.max(end, n.endBeat), spanStart);
+  assertGenerationBudget(Math.ceil((spanEnd - spanStart) / GRID_STEP), "countermelody grid");
+  const meanPitch = melody.notes.reduce((sum, n) => sum + n.note.pitch, 0) / melody.notes.length;
   const defaultCenter = register === "below" ? meanPitch - REGISTER_OFFSET : meanPitch + REGISTER_OFFSET;
   const low = opts.pitchLow ?? Math.round(defaultCenter) - DEFAULT_HALF_RANGE;
   const high = opts.pitchHigh ?? Math.round(defaultCenter) + DEFAULT_HALF_RANGE;
+  assertInteger(low, "countermelody pitchLow");
+  assertInteger(high, "countermelody pitchHigh");
+  if (low > high) {
+    throw new RangeError(
+      `countermelody pitchLow must not exceed pitchHigh; received ${low} > ${high}`
+    );
+  }
+  assertGenerationBudget(high - low + 1, "countermelody pitch candidates");
+  assertGenerationBudget(opts.chordChangeBeats?.length ?? 0, "chord change beats");
+  for (let index = 0; index < (opts.chordChangeBeats?.length ?? 0); index += 1) {
+    assertRange(
+      opts.chordChangeBeats?.[index] ?? Number.NaN,
+      0,
+      Number.MAX_SAFE_INTEGER,
+      `chordChangeBeats[${index}]`
+    );
+  }
   const center = (low + high) / 2;
   const onsets = rhythm === "follow" ? followOnsets(melody) : complementOnsets(melody, ts, spanStart, spanEnd, rng);
+  assertGenerationBudget(onsets.length * (high - low + 1), "countermelody search");
   const out = [];
   let prevPitch;
-  let prevOnset;
-  for (const beat of onsets) {
+  for (let onsetIndex = 0; onsetIndex < onsets.length; onsetIndex += 1) {
+    const beat = onsets[onsetIndex];
+    if (beat === void 0) {
+      continue;
+    }
+    const nextOnset = onsets[onsetIndex + 1];
+    const endBeat = nextOnset ?? Math.max(spanEnd, beat + GRID_STEP);
     const melNote = melodyNoteAt(melody, beat);
     const melPitch = melNote?.pitch;
-    const melPrev = prevOnset !== void 0 ? melodyNoteAt(melody, prevOnset)?.pitch : void 0;
+    const melodyVoice = melodySnapshotAt(melody, beat);
+    const melPrev = melodyVoice?.prevPitch;
     const chord = opts.chordAt(beat);
-    const otherVoices = melPitch !== void 0 ? [{ pitch: melPitch, prevPitch: melPrev }] : [];
+    const otherVoices = melodyVoice !== void 0 ? [melodyVoice] : [];
     const candidates = enumerateSafePitches(
       {
         profile,
@@ -2576,15 +2978,26 @@ function generateCounterMelody(opts) {
       high
     );
     let bestPitch;
+    let bestWorstSafety = 2 /* Dissonant */;
     let bestScore = Number.NEGATIVE_INFINITY;
     for (const candidate of candidates) {
+      const worstSafety = heldPitchSafety(
+        candidate,
+        beat,
+        endBeat,
+        prevPitch,
+        melody,
+        opts,
+        profile,
+        register,
+        low,
+        high,
+        ts
+      );
+      if (worstSafety === null || worstSafety === 2 /* Dissonant */) {
+        continue;
+      }
       if (melPitch !== void 0) {
-        if (register === "below" && candidate >= melPitch) {
-          continue;
-        }
-        if (register === "above" && candidate <= melPitch) {
-          continue;
-        }
         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)) {
@@ -2592,29 +3005,24 @@ function generateCounterMelody(opts) {
         }
       }
       const score = scoreCandidate(candidate, melPitch, melPrev, prevPitch, chord, center);
-      const tie = Math.abs(score - bestScore) <= EPS6 && candidate < (bestPitch ?? Number.POSITIVE_INFINITY);
-      if (score > bestScore + EPS6 || tie) {
+      const tie = Math.abs(score - bestScore) <= EPS7 && candidate < (bestPitch ?? Number.POSITIVE_INFINITY);
+      if (worstSafety < bestWorstSafety || worstSafety === bestWorstSafety && (score > bestScore + EPS7 || tie)) {
+        bestWorstSafety = worstSafety;
         bestScore = score;
         bestPitch = candidate;
       }
     }
-    const pitch = bestPitch ?? fallbackPitch(melPitch, prevPitch, center, register, low, high, opts.key);
+    if (bestPitch === void 0) {
+      prevPitch = void 0;
+      continue;
+    }
+    const pitch = bestPitch;
     const velocity = Math.max(
       1,
       Math.min(127, Math.round((melNote?.velocity ?? DEFAULT_MELODY_VELOCITY) - VELOCITY_DROP))
     );
-    out.push({ pitch, startBeat: beat, durationBeat: GRID_STEP, velocity });
+    out.push({ pitch, startBeat: beat, durationBeat: endBeat - beat, velocity });
     prevPitch = pitch;
-    prevOnset = beat;
-  }
-  for (let i = 0; i < out.length; i += 1) {
-    const note = out[i];
-    if (!note) {
-      continue;
-    }
-    const next = out[i + 1];
-    const end = next ? next.startBeat : Math.max(spanEnd, note.startBeat + GRID_STEP);
-    note.durationBeat = end - note.startBeat;
   }
   return out;
 }
@@ -3334,9 +3742,10 @@ function generateHiHatForBeat(ctx, sec) {
 
 // src/generate/drums/euclid.ts
 function euclideanRhythm(pulses, steps, rotation = 0) {
-  if (steps < 1) {
-    return [];
-  }
+  assertPositiveInt(steps, "euclidean steps");
+  assertInteger(pulses, "euclidean pulses");
+  assertInteger(rotation, "euclidean rotation");
+  assertGenerationBudget(steps, "euclidean pattern steps");
   const p = Math.max(0, Math.min(pulses, steps));
   const base = bjorklund(p, steps);
   const shift = (rotation % steps + steps) % steps;
@@ -3345,18 +3754,6 @@ function euclideanRhythm(pulses, steps, rotation = 0) {
   }
   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);
@@ -3688,19 +4085,6 @@ 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") {
@@ -3822,7 +4206,7 @@ function getPercussionConfig(mood, section) {
   };
 }
 function generateAuxPercussionForBar(track, barStart, config, role, densityMult, rng, bpm) {
-  if (role === "minimal" || role === "fxOnly") {
+  if (role === "minimal") {
     return;
   }
   if (config.tambourine) {
@@ -3871,6 +4255,16 @@ function generateAuxPercussionForBar(track, barStart, config, role, densityMult,
 
 // src/generate/drums/index.ts
 function generateDrums(opts) {
+  assertPositiveInt(opts.bars, "drum bars");
+  assertRange(opts.bpm, Number.MIN_VALUE, 1e3, "drum bpm");
+  assertRange(opts.density, 0, 1, "drum density");
+  assertGenerationBudget(opts.bars * 128, "drum hits");
+  if (opts.euclideanKick) {
+    const steps = opts.euclideanKick.steps ?? 16;
+    assertInteger(steps, "euclidean steps", 1, 16);
+    assertInteger(opts.euclideanKick.pulses, "euclidean pulses");
+    assertInteger(opts.euclideanKick.rotation ?? 0, "euclidean rotation");
+  }
   const track = new HitList();
   const rng = createRng(opts.seed ?? 0);
   const mapping = mapStyle(opts.style);
@@ -3907,15 +4301,8 @@ function generateDrums(opts) {
   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 euclidSteps = opts.euclideanKick?.steps ?? 16;
+  const euclidKick = opts.euclideanKick ? euclideanRhythm(opts.euclideanKick.pulses, euclidSteps, 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) {
@@ -3931,12 +4318,10 @@ function generateDrums(opts) {
       barHasOpenHh = !track.hasCrashNear(barStart + openHhBeatIndex);
     }
     let kick;
-    if (euclidKick) {
-      kick = euclidKick;
-    } else if (reuseSectionKick) {
+    if (!euclidKick && reuseSectionKick) {
       sectionKick ??= getKickPattern(section, style, 0, rng);
       kick = sectionKick;
-    } else {
+    } else if (!euclidKick) {
       kick = getKickPattern(section, style, bar, rng);
     }
     const inLift = isInPreChorusLift(section, bar, opts.bars, section === "b");
@@ -3977,7 +4362,23 @@ function generateDrums(opts) {
         if (inLift) {
           generatePreChorusBuildup(ctx, sec, isLastBar);
         }
-        generateKickForBeat(ctx, sec, kick);
+        if (euclidKick && !inLift) {
+          const stepLength = 4 / euclidSteps;
+          for (let step = 0; step < euclidKick.length; step += 1) {
+            const onset = step * stepLength;
+            if (euclidKick[step] && Math.floor(onset) === beat) {
+              const wholeBeat = Math.abs(onset - Math.round(onset)) < 1e-9;
+              track.add(
+                GM.BD,
+                barStart + onset,
+                Math.min(0.5, stepLength),
+                velocity * (wholeBeat ? 1 : 0.85)
+              );
+            }
+          }
+        } else if (kick) {
+          generateKickForBeat(ctx, sec, kick);
+        }
         generateSnareForBeat(ctx, sec, section === "intro" && bar === 0);
         if (sec.useGhostNotes && !inLift) {
           generateGhostNotesForBeat(ctx, sec);
@@ -3994,10 +4395,19 @@ function generateDrums(opts) {
         }
       }
     }
+    let percussionConfig = getPercussionConfig(percMood, section);
+    if (role === "fxOnly" && !percussionConfig.tambourine && !percussionConfig.shaker && !percussionConfig.handclap) {
+      percussionConfig = {
+        tambourine: false,
+        shaker: true,
+        handclap: false,
+        shaker16th: false
+      };
+    }
     generateAuxPercussionForBar(
       track,
       barStart,
-      getPercussionConfig(percMood, section),
+      percussionConfig,
       role,
       densityMult,
       rng,
@@ -4018,10 +4428,16 @@ var MIN_VELOCITY = 1;
 var MAX_VELOCITY = 127;
 function humanize(events, opts = {}) {
   const ts = opts.ts ?? DEFAULT_TS3;
+  assertTimeSignature(ts);
+  assertNoteEvents(events, "humanize events");
   const timing = opts.timing ?? DEFAULT_TIMING;
   const velocityJitter = opts.velocity ?? DEFAULT_VELOCITY_JITTER;
   const accent = opts.accent ?? DEFAULT_ACCENT;
   const baseVelocity = opts.baseVelocity ?? DEFAULT_BASE_VELOCITY;
+  assertRange(timing, 0, Number.MAX_SAFE_INTEGER, "humanize timing");
+  assertRange(velocityJitter, 0, 127, "humanize velocity jitter");
+  assertRange(accent, 0, 127, "humanize accent");
+  assertRange(baseVelocity, 0, 127, "humanize base velocity");
   const rng = createRng(opts.seed ?? 0);
   return events.map((event) => {
     const timingOffset = rng.float(-timing, timing);
@@ -4054,8 +4470,12 @@ function quantizeToGrid(beat, barBeats, subdivision, slotsPerBar) {
   };
 }
 function extractGrooveTemplate(events, ts, subdivision) {
+  assertTimeSignature(ts);
+  assertNoteEvents(events, "groove source events");
+  assertPositiveInt(subdivision, "groove subdivision");
   const barBeats = beatsPerBar(ts);
   const slotsPerBar = Math.round(barBeats * subdivision);
+  assertGenerationBudget(slotsPerBar, "groove template slots");
   const offsetSums = new Array(slotsPerBar).fill(0);
   const velocitySums = new Array(slotsPerBar).fill(0);
   const counts = new Array(slotsPerBar).fill(0);
@@ -4090,6 +4510,14 @@ function extractGrooveTemplate(events, ts, subdivision) {
   return { subdivision, slotsPerBar, slots, ts };
 }
 function applyGrooveTemplate(events, template, ts) {
+  assertTimeSignature(ts);
+  assertNoteEvents(events, "groove target events");
+  assertPositiveInt(template.subdivision, "template subdivision");
+  assertPositiveInt(template.slotsPerBar, "template slotsPerBar");
+  assertGenerationBudget(template.slots.length, "template slots");
+  if (template.slots.length !== template.slotsPerBar) {
+    throw new RangeError("template slots length must equal slotsPerBar");
+  }
   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)}`
@@ -4119,32 +4547,17 @@ function applyGrooveTemplate(events, template, ts) {
 function roleOf(pitch, chord, chordId = 0) {
   const interval = ((Math.trunc(pitch) - chord.rootPc) % 12 + 12) % 12;
   const tones = new Set(chord.intervals.map((i) => (i % 12 + 12) % 12));
-  const hasHigherSeventh = tones.has(10) || tones.has(11);
   const hasThird = tones.has(3) || tones.has(4);
   const isSuspendedTone = !hasThird && (interval === 5 && tones.has(5) || interval === 2 && tones.has(2));
+  const chordRole = chordToneRole(pitch, chord);
   let role;
   let lock;
-  if (interval === 0) {
-    role = "root";
-    lock = "identity";
-  } else if (isSuspendedTone) {
-    role = "third";
-    lock = "quality";
-  } else if (interval === 3 || interval === 4) {
+  if (isSuspendedTone) {
     role = "third";
     lock = "quality";
-  } else if (interval === 6 || interval === 7 || interval === 8) {
-    role = "fifth";
-    lock = "voicing";
-  } else if (interval === 9 && tones.has(3) && tones.has(6) && !hasHigherSeventh) {
-    role = "seventh";
-    lock = "voicing";
-  } else if (interval === 9 && tones.has(9) && !hasHigherSeventh) {
-    role = "sixth";
-    lock = "voicing";
-  } else if (interval === 10 || interval === 11) {
-    role = "seventh";
-    lock = "voicing";
+  } else if (chordRole !== null) {
+    role = chordRole;
+    lock = chordRole === "root" ? "identity" : chordRole === "third" ? "quality" : "voicing";
   } else {
     role = "tension";
     lock = "voicing";
@@ -4162,16 +4575,6 @@ var TIE_BREAK_JITTER = 1e-6;
 function pitchClass10(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
-function mulberry32(seed) {
-  let state = seed >>> 0;
-  return () => {
-    state = state + 1831565813 >>> 0;
-    let t = state;
-    t = Math.imul(t ^ t >>> 15, t | 1);
-    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
-    return ((t ^ t >>> 14) >>> 0) / 4294967296;
-  };
-}
 function inferKey(melody) {
   let best = majorKey(0);
   let bestScore = Number.NEGATIVE_INFINITY;
@@ -4210,7 +4613,6 @@ function buildCandidates(key, reharmonize) {
     secondaryDominant: false,
     base: 0
   }));
-  const tonic = tones[0] ?? 0;
   if (reharmonize !== "diatonic") {
     for (const target of [1, 3, 4, 5]) {
       const targetRoot = tones[target] ?? 0;
@@ -4224,26 +4626,29 @@ function buildCandidates(key, reharmonize) {
     }
   }
   if (reharmonize === "borrowed") {
-    candidates.push({
-      rootPc: (tonic + 10) % 12,
-      quality: "maj",
-      secondaryDominant: false,
-      base: 2
-    });
-    candidates.push({
-      rootPc: (tonic + 8) % 12,
-      quality: "maj",
-      secondaryDominant: false,
-      base: 2
-    });
-    candidates.push({
-      rootPc: (tonic + 5) % 12,
-      quality: "min",
-      secondaryDominant: false,
-      base: 2
-    });
+    const parallel = parallelKey(key);
+    const parallelTones = scaleTonesInDegreeOrder(parallel);
+    for (let degree = 0; degree < parallelTones.length; degree += 1) {
+      const chord = diatonicTriad(degree, parallel);
+      if (!isDiatonic(chord, key)) {
+        candidates.push({
+          rootPc: chord.rootPc,
+          quality: chord.quality,
+          secondaryDominant: false,
+          base: 1.25
+        });
+      }
+    }
   }
-  return candidates;
+  const seen = /* @__PURE__ */ new Set();
+  return candidates.filter((candidate) => {
+    const id = `${candidate.rootPc}:${candidate.quality}`;
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
 }
 function emissionCost(seg, cand, melody, key) {
   const pcs = chordPitchClasses(makeChord(cand.rootPc, cand.quality));
@@ -4347,20 +4752,37 @@ function harmonizeOnce(melody, key, candidates, segments, jitter) {
   return { cost: bestCost, path };
 }
 function harmonizeMelody(opts) {
+  const noteIndex = createNoteEventIndex(opts.melody);
   const key = opts.key === "infer" ? inferKey(opts.melody) : opts.key;
   const candidates = buildCandidates(key, opts.reharmonize);
   const candAt = (i) => candidates[i] ?? FALLBACK;
-  const rng = mulberry32(opts.seed ?? 0);
-  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 rng = createRng(opts.seed ?? 0);
+  const jitter = candidates.map(() => rng.next() * TIE_BREAK_JITTER);
+  const melodyEnd = noteIndex.notes.reduce((m, n) => Math.max(m, n.endBeat), 0);
+  const requestedHr = assertRange(
+    opts.harmonicRhythm,
+    Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    "harmonic rhythm"
+  );
+  const hr = Math.max(0.25, requestedHr);
   const segCount = Math.max(1, Math.ceil(melodyEnd / hr));
-  const segments = [];
-  for (let s = 0; s < segCount; s += 1) {
-    const startBeat = s * hr;
-    const endBeat = startBeat + hr;
-    const noteIndices = opts.melody.map((n, i) => ({ n, i })).filter(({ n }) => n.startBeat < endBeat && n.startBeat + n.durationBeat > startBeat).map(({ i }) => i);
-    segments.push({ startBeat, endBeat, noteIndices });
+  assertGenerationBudget(segCount, "harmonic segments");
+  assertGenerationBudget(segCount * candidates.length * candidates.length, "harmonization search");
+  const segments = Array.from({ length: segCount }, (_, s) => ({
+    startBeat: s * hr,
+    endBeat: (s + 1) * hr,
+    noteIndices: []
+  }));
+  let memberships = 0;
+  for (const indexed of noteIndex.notes) {
+    const first = Math.max(0, Math.floor(indexed.note.startBeat / hr));
+    const lastExclusive = Math.min(segCount, Math.ceil(indexed.endBeat / hr - Number.EPSILON));
+    memberships += Math.max(0, lastExclusive - first);
+    assertGenerationBudget(memberships, "note-to-segment memberships");
+    for (let segment = first; segment < lastExclusive; segment += 1) {
+      segments[segment]?.noteIndices.push(indexed.originalIndex);
+    }
   }
   const transposes = [0];
   if (opts.placement.transposeSearch) {
@@ -4407,11 +4829,11 @@ function harmonizeMelody(opts) {
     }
     return chord;
   });
-  const melodyRoles = bestMelody.map((note, noteIndex) => {
+  const melodyRoles = bestMelody.map((note, noteIndex2) => {
     const segIdx = Math.min(segments.length - 1, Math.max(0, Math.floor(note.startBeat / hr)));
     const cand = candAt(bestPath[segIdx] ?? 0);
     const chord = makeChord(cand.rootPc, cand.quality);
-    return { noteIndex, role: roleOf(note.pitch, chord).role };
+    return { noteIndex: noteIndex2, role: roleOf(note.pitch, chord).role };
   });
   return { transposeSemitones: bestTs, key, chords, melodyRoles };
 }
@@ -4458,29 +4880,30 @@ function nearestChordTone(pitch, chord) {
   return pitch;
 }
 function cellOrigin(notes) {
-  return notes.length === 0 ? 0 : Math.min(...notes.map((n) => n.startBeat));
+  let origin = Number.POSITIVE_INFINITY;
+  for (const note of notes) {
+    origin = Math.min(origin, note.startBeat);
+  }
+  return Number.isFinite(origin) ? origin : 0;
+}
+function cellEnd(notes) {
+  let end = Number.NEGATIVE_INFINITY;
+  for (const note of notes) {
+    end = Math.max(end, note.startBeat + note.durationBeat);
+  }
+  return Number.isFinite(end) ? end : 0;
 }
 function cellSpan(cell) {
   if (cell.notes.length === 0) {
     return 0;
   }
   const start = cellOrigin(cell.notes);
-  const end = Math.max(...cell.notes.map((n) => n.startBeat + n.durationBeat));
+  const end = cellEnd(cell.notes);
   return end - start;
 }
 function clone(cell) {
   return { notes: cell.notes.map((n) => ({ ...n })) };
 }
-function mulberry322(seed) {
-  let state = seed >>> 0;
-  return () => {
-    state = state + 1831565813 >>> 0;
-    let t = state;
-    t = Math.imul(t ^ t >>> 15, t | 1);
-    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
-    return ((t ^ t >>> 14) >>> 0) / 4294967296;
-  };
-}
 function contourOffsets(contour, count) {
   const offsets = [];
   for (let i = 0; i < count; i += 1) {
@@ -4503,19 +4926,21 @@ function contourOffsets(contour, count) {
 }
 function generateMotif(opts) {
   const contour = opts.contour ?? "arch";
-  const bars = Math.max(1, Math.trunc(opts.bars));
+  const bars = assertPositiveInt(opts.bars, "motif bars");
   const totalBeats = bars * 4;
   const noteCount = Math.max(3, bars * 2);
+  assertGenerationBudget(noteCount, "motif notes");
   const beatsPerNote = totalBeats / noteCount;
-  const rng = mulberry322(opts.seed ?? 0);
-  const jitterProb = Math.min(1, Math.max(0, opts.jitter ?? 0));
+  const rng = createRng(opts.seed ?? 0);
+  const requestedJitter = assertFiniteNumber(opts.jitter ?? 0, "motif jitter");
+  const jitterProb = Math.min(1, Math.max(0, requestedJitter));
   const tonic = pitchClass11(opts.key.rootPc) + 60;
   const offsets = contourOffsets(contour, noteCount);
   const notes = [];
   for (let i = 0; i < noteCount; i += 1) {
     let jitter = 0;
-    if (jitterProb > 0 && rng() < jitterProb) {
-      jitter = rng() < 0.5 ? 1 : -1;
+    if (jitterProb > 0 && rng.next() < jitterProb) {
+      jitter = rng.next() < 0.5 ? 1 : -1;
     }
     let pitch = stepDiatonic(tonic, (offsets[i] ?? 0) + jitter, opts.key);
     const startBeat = i * beatsPerNote;
@@ -4527,6 +4952,16 @@ function generateMotif(opts) {
   return { notes };
 }
 function transformMotif(cell, t, amount, key) {
+  assertNoteEvents(cell.notes, "motif notes");
+  if (amount !== void 0) {
+    assertFiniteNumber(amount, "motif transform amount");
+  }
+  if ((t === "transposeDiatonic" || t === "sequence") && amount !== void 0) {
+    assertInteger(amount, "diatonic transform amount");
+  }
+  if ((t === "augment" || t === "diminish") && amount !== void 0 && amount <= 0) {
+    throw new RangeError("time transform amount must be positive");
+  }
   const notes = cell.notes;
   switch (t) {
     case "transposeChromatic": {
@@ -4553,7 +4988,7 @@ function transformMotif(cell, t, amount, key) {
         return { notes: [] };
       }
       const start = cellOrigin(notes);
-      const end = Math.max(...notes.map((n) => n.startBeat + n.durationBeat));
+      const end = cellEnd(notes);
       return {
         notes: notes.map((n) => ({
           pitch: n.pitch,
@@ -4586,8 +5021,10 @@ function scaleTime(cell, factor) {
   };
 }
 function developMotif(cell, timeline, key, bars) {
+  assertPositiveInt(bars, "development bars");
+  assertNoteEvents(cell.notes, "motif notes");
   const span = cellSpan(cell);
-  const totalBeats = Math.max(1, Math.trunc(bars)) * 4;
+  const totalBeats = bars * 4;
   const origin = cellOrigin(cell.notes);
   const out = [];
   if (span <= 0) {
@@ -4595,6 +5032,7 @@ function developMotif(cell, timeline, key, bars) {
   }
   const tileSpan = Math.max(span, MIN_TILE_SPAN);
   const tileCount = Math.ceil(totalBeats / tileSpan);
+  assertGenerationBudget(tileCount * cell.notes.length, "developed motif notes");
   for (let k = 0; k < tileCount; k += 1) {
     const offset = k * tileSpan;
     for (const n of cell.notes) {
@@ -4793,16 +5231,6 @@ function progressions() {
 function progressionsByStyle(style) {
   return progressions().filter((p) => p.styles.includes(style));
 }
-function mulberry323(seed) {
-  let state = seed >>> 0;
-  return () => {
-    state = state + 1831565813 >>> 0;
-    let t = state;
-    t = Math.imul(t ^ t >>> 15, t | 1);
-    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
-    return ((t ^ t >>> 14) >>> 0) / 4294967296;
-  };
-}
 function degreeToRootPc(degree, key) {
   if (degree >= 0 && degree <= 6) {
     const tones = scaleTonesInDegreeOrder(key);
@@ -4824,6 +5252,8 @@ function autoQuality(degree, key) {
   return "maj";
 }
 function generateProgression(opts) {
+  assertPositiveInt(opts.bars, "progression bars");
+  assertGenerationBudget(opts.bars, "progression chords");
   const seed = opts.seed ?? 0;
   let preset;
   if (opts.presetId !== void 0) {
@@ -4835,8 +5265,8 @@ function generateProgression(opts) {
   if (preset === void 0) {
     const pool = PRESETS.filter((p) => p.styles.includes(opts.style));
     const candidates = pool.length > 0 ? pool : PRESETS;
-    const rng = mulberry323(seed);
-    const index = Math.floor(rng() * candidates.length) % candidates.length;
+    const rng = createRng(seed);
+    const index = Math.floor(rng.next() * candidates.length) % candidates.length;
     preset = candidates[index] ?? PRESETS[0];
   }
   const degrees = preset?.degrees ?? [0];
@@ -4854,7 +5284,7 @@ function generateProgression(opts) {
   }
   if (opts.reharmonize) {
     const tonicPc = (opts.key.rootPc % 12 + 12) % 12;
-    const rrng = mulberry323((seed ^ 2654435769) >>> 0);
+    const rrng = createRng((seed ^ 2654435769) >>> 0);
     for (let i = 0; i < chords.length - 1; i += 1) {
       const cur = chords[i];
       const next = chords[i + 1];
@@ -4868,7 +5298,7 @@ function generateProgression(opts) {
       if (targetsTonic || alreadySecondary || isResolutionTarget) {
         continue;
       }
-      if (rrng() < 0.5) {
+      if (rrng.next() < 0.5) {
         chords[i] = {
           rootPc: domRoot,
           quality: "dom7",
@@ -4896,11 +5326,6 @@ function isStableTarget(chord) {
   const hasThird = hasInterval(chord, 3) || hasInterval(chord, 4);
   return hasFifth && hasThird && !isDominantType(chord);
 }
-function triadPitchClasses(chord) {
-  const third = hasInterval(chord, 4) ? 4 : hasInterval(chord, 3) ? 3 : 4;
-  const fifth = hasInterval(chord, 8) ? 8 : hasInterval(chord, 6) ? 6 : 7;
-  return [mod123(chord.rootPc), mod123(chord.rootPc + third), mod123(chord.rootPc + fifth)];
-}
 function commonToneCount(a, b) {
   const set = new Set(b);
   return a.filter((pc) => set.has(pc)).length;
@@ -4918,7 +5343,7 @@ function sameChord2(a, b) {
 }
 var THIRD_OFFSETS = [3, 4, 8, 9];
 function substituteChord(chord, key, opts) {
-  const original = triadPitchClasses(chord);
+  const original = chordPitchClasses(chord);
   const candidates = [];
   if (isDominantType(chord)) {
     candidates.push({ chord: makeChord(mod123(chord.rootPc + 6), "dom7"), type: "tritone" });
@@ -5039,11 +5464,15 @@ function generateRhythm(ts, opts = {}) {
   const seed = opts.seed ?? 0;
   const bars = opts.bars ?? DEFAULT_BARS;
   const subdivision = opts.subdivision ?? DEFAULT_SUBDIVISION;
-  const density = Math.min(1, Math.max(0, opts.density ?? DEFAULT_DENSITY));
+  const requestedDensity = assertFiniteNumber(opts.density ?? DEFAULT_DENSITY, "rhythm density");
+  const density = Math.min(1, Math.max(0, requestedDensity));
+  assertPositiveInt(bars, "rhythm bars");
+  assertPositiveInt(subdivision, "rhythm subdivision");
   const barBeats = beatsPerBar(ts);
   const spanBeats = barBeats * bars;
   const step = 1 / subdivision;
   const slotCount = Math.round(spanBeats * subdivision);
+  assertGenerationBudget(slotCount, "rhythm grid slots");
   const slotsPerBar = Math.round(barBeats * subdivision);
   const rng = createRng(seed);
   const positions = [];
@@ -5348,10 +5777,58 @@ function spellScale(tonic, key) {
 function spellPitchClasses(pcs, tonic, key) {
   return pcs.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);
 }
 function noteNames(notes) {
   return notes.map(formatNote);
@@ -5644,12 +6121,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 }));
   }
@@ -5668,6 +6156,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;
@@ -5692,8 +6182,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) {
@@ -5799,7 +6292,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 = pitchClass14(chord.rootPc);
   const bassPc = pitchClass14(chord.bassPc ?? chord.rootPc);
   const omitRoot = style === "rootless" || opts?.rootless === true;
@@ -5815,11 +6313,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 [];
@@ -5848,6 +6346,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) => pitchClass14(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);
 }
 
@@ -6143,7 +6653,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;
   }
   /**
@@ -6155,8 +6669,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.
@@ -6183,8 +6702,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))
     );
   }
@@ -6194,8 +6713,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). */
@@ -6353,8 +6872,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);
   }
@@ -6706,6 +7231,7 @@ var Key = class _Key {
   BLUES_MASK,
   CHROMATIC_MASK,
   Chord,
+  DEFAULT_GENERATION_BUDGET,
   DORIAN_MASK,
   HARMONIC_MINOR_MASK,
   Interval,
@@ -6735,6 +7261,14 @@ var Key = class _Key {
   analyzeChord,
   analyzeVoice,
   applyGrooveTemplate,
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvent,
+  assertNoteEvents,
+  assertPositiveInt,
+  assertRange,
+  assertTimeSignature,
   availableTensions,
   avoidNotes,
   barPositionToBeat,
@@ -6753,6 +7287,7 @@ var Key = class _Key {
   chordToRoman,
   chordToneRole,
   classifyInterval,
+  createNoteEventIndex,
   createRng,
   createsHiddenParallelPerfect,
   createsParallelOctave,