@libraz/libcantus 1.3.0 → 1.4.0

package/dist/{chunk-CPMB7P75.js → chunk-FK3DGAIZ.js}

@@ -20,7 +20,6 @@ import {
   functionOf,
   ioiBinIndex,
   isDiatonic,
-  isMinorKey,
   keyLookup,
   melodicSimilarity,
   onsetSimilarity,
@@ -30,7 +29,7 @@ import {
   rhythmLevel,
   romanToChord,
   syncopationSimilarity
-} from "./chunk-GNVN4PPJ.js";
+} from "./chunk-FJFULJZE.js";
 import {
   ALGORITHM_VERSION,
   LIMBS,
@@ -42,16 +41,20 @@ import {
   includeAt,
   instrumentRange,
   resolveAlgorithmVersion,
+  scaleUnitDraw,
   toStringedProfile
-} from "./chunk-7KG3RTYS.js";
+} from "./chunk-VL5NXVCN.js";
 import {
-  createNoteEventIndex
-} from "./chunk-PUKJP2Z5.js";
+  canonicalNoteOrder,
+  createNoteEventIndex,
+  soundingIndices
+} from "./chunk-TXFWSU5D.js";
 import {
   chordScales,
   roleOf
-} from "./chunk-NB25P3EH.js";
+} from "./chunk-2G5MCGYU.js";
 import {
+  cadencesThroughRaisedSeventh,
   chordPitchClasses,
   chordQualities,
   chordToneRole,
@@ -63,6 +66,7 @@ import {
   fifthPcOf,
   heptatonicFrameOf,
   isForbiddenMelodicLeap,
+  isNativeDominantSeventh,
   isScaleTone,
   leadingTonePcOf,
   majorKey,
@@ -75,7 +79,6 @@ import {
   scaleLadderPitch,
   scaleLadderPosition,
   scaleOf,
-  scaleSystemOf,
   scaleTonesInDegreeOrder,
   shiftByScaleDegrees,
   soundsDominantSeventh,
@@ -84,7 +87,7 @@ import {
   toChordData,
   toKeyScale,
   tonicizableDegrees
-} from "./chunk-RFIBF2RR.js";
+} from "./chunk-H7FVMBUC.js";
 import {
   ARTICULATIONS,
   BEAT_EPS,
@@ -109,6 +112,7 @@ import {
   assertRange,
   assertRecord,
   assertTimeSignature,
+  barIndexAt,
   barStartBeat,
   beatsPerBar,
   beatsPerBarAt,
@@ -130,7 +134,7 @@ import {
   toSpelledInterval,
   transposeByInterval,
   transposeNote
-} from "./chunk-AGOVW7U6.js";
+} from "./chunk-YYVXRV3V.js";
 
 // src/generate/context/draw.ts
 var DRAW_METHODS = ["at", "prob", "range", "float"];
@@ -185,7 +189,7 @@ function drawsFrom(rng, ...prefix) {
         );
       }
       assertFiniteNumber(hi - lo, "float span");
-      return lo + at2(...path) * (hi - lo);
+      return scaleUnitDraw(at2(...path), lo, hi);
     }
   };
 }
@@ -410,7 +414,9 @@ var GENRES = Object.freeze([
 ]);
 var PROVENANCE_BASES = Object.freeze(["idiom", "construction", "traditional"]);
 function sameTs(a, b) {
-  return a.numerator === b.numerator && a.denominator === b.denominator;
+  const grouping = a.grouping;
+  const theirs = b.grouping;
+  return a.numerator === b.numerator && a.denominator === b.denominator && (grouping === void 0 || theirs === void 0 ? grouping === theirs : Array.isArray(grouping) && grouping.length === theirs.length && grouping.every((entry, index) => entry === theirs[index]));
 }
 function fitsQuery(entry, query) {
   const candidate = assertRecord(entry, "vocabulary entry");
@@ -571,6 +577,14 @@ function sustainsShift(semitones, stepBeats, bpm, difficulty) {
 
 // src/generate/context/index.ts
 var DEFAULT_SEED = 0;
+function nullish(value) {
+  return value === void 0 || value === null;
+}
+function assertPositionalSource(rng) {
+  const source = assertRecord(rng, "ctx.rng");
+  assertFunction(source.at, "ctx.rng.at");
+  return source;
+}
 var VERSION_SEGMENT = "v";
 function resolveContext(input) {
   if (input !== null && typeof input !== "number" && input !== void 0) {
@@ -581,18 +595,16 @@ function resolveContext(input) {
   }
   const ctx = typeof input === "number" ? { seed: input } : input ?? { seed: DEFAULT_SEED };
   const seed = assertInteger(ctx.seed ?? DEFAULT_SEED, "seed", 0, 4294967295);
-  const complexity = ctx.complexity ?? {};
+  const complexity = nullish(ctx.complexity) ? {} : assertRecord(ctx.complexity, "ctx.complexity");
   const rhythmic = complexity.rhythmic === void 0 ? void 0 : assertRange(complexity.rhythmic, 0, 1, "complexity rhythmic");
   const harmonic = complexity.harmonic === void 0 ? void 0 : assertRange(complexity.harmonic, 0, 1, "complexity harmonic");
   const ornament2 = complexity.ornament === void 0 ? void 0 : assertRange(complexity.ornament, 0, 1, "complexity ornament");
   const difficulty = complexity.difficulty === void 0 ? void 0 : assertDifficulty(complexity.difficulty);
   const bpm = ctx.bpm === void 0 ? void 0 : assertRange(ctx.bpm, Number.MIN_VALUE, 1e3, "bpm");
   const algorithmVersion = resolveAlgorithmVersion(ctx.algorithmVersion);
-  const supplied = ctx.rng;
-  const instruments = ctx.instruments;
-  const vocabulary = (ctx.vocabulary ?? []).map(
-    (entry, index) => assertVocabulary(entry, `vocabulary[${index}]`)
-  );
+  const supplied = ctx.rng ? assertPositionalSource(ctx.rng) : void 0;
+  const instruments = nullish(ctx.instruments) ? void 0 : assertRecord(ctx.instruments, "ctx.instruments");
+  const vocabulary = (nullish(ctx.vocabulary) ? [] : assertArray(ctx.vocabulary, "ctx.vocabulary")).map((entry, index) => assertVocabulary(entry, `vocabulary[${index}]`));
   return {
     seed,
     rhythmic,
@@ -601,7 +613,7 @@ function resolveContext(input) {
     difficulty,
     bpm,
     algorithmVersion,
-    instrument: (part) => instruments?.[part],
+    instrument: (part) => instruments !== void 0 && Object.hasOwn(instruments, part) ? instruments[part] : void 0,
     vocabulary,
     part: (name) => supplied ? drawsFrom(supplied, name, VERSION_SEGMENT, algorithmVersion) : drawsFrom(createPositionalRng(deriveSeed(seed, name, VERSION_SEGMENT, algorithmVersion)))
   };
@@ -753,6 +765,7 @@ function bassRegister(named, given, octave) {
 var BAR_STEPS = 16;
 var BEAT_STEPS = 4;
 var STEP_BEATS = 1 / BEAT_STEPS;
+var FIGURE_RATES = ["straight", "half", "double"];
 function assertGridEvents(events) {
   assertArray(events, "figure events");
   events.forEach((event, index) => {
@@ -767,6 +780,16 @@ function assertSpanSteps(spanSteps) {
 function streamOf(event) {
   return event.limb ?? event.voice ?? "";
 }
+function positionKey(event, step) {
+  return `${streamOf(event)}@${step}`;
+}
+function drawKey(event) {
+  const stream = `${streamOf(event)}`;
+  return stream === "" ? [event.step] : [stream, event.step];
+}
+function halvedStep(step) {
+  return Number.isInteger(step) ? Math.round(step / 2) : step / 2;
+}
 var FIGURE_TS = { numerator: 4, denominator: 4 };
 function subdivisionBeats(ts) {
   const pulse2 = pulseBeats(ts);
@@ -789,46 +812,57 @@ function stepWeight(step, ts) {
 function thin(events, amount, ts) {
   const figure = assertGridEvents(events);
   assertRange(amount, 0, 1, "thin amount");
-  const signature = meterAt(0, toMeterData(ts, "ts"));
+  return thinFigure(figure, amount, meterAt(0, toMeterData(ts, "ts")));
+}
+function thinFigure(figure, amount, ts) {
   const floor = Math.min(4, Math.floor(amount * 5));
-  return figure.filter((event) => stepWeight(event.step, signature) >= floor);
+  return figure.filter((event) => stepWeight(event.step, ts) >= floor);
 }
 function double(events, spanSteps = BAR_STEPS) {
   assertSpanSteps(spanSteps);
   const sorted = [...assertGridEvents(events)].sort((a, b) => a.step - b.step);
-  const out = [];
-  for (let i = 0; i < sorted.length; i += 1) {
+  const nextStep = [];
+  const following = /* @__PURE__ */ new Map();
+  for (let i = sorted.length - 1; i >= 0; i -= 1) {
     const event = sorted[i];
-    if (!event) {
-      continue;
-    }
+    const stream = streamOf(event);
+    nextStep[i] = following.get(stream) ?? spanSteps;
+    following.set(stream, event.step);
+  }
+  const out = [];
+  sorted.forEach((event, i) => {
     out.push(event);
-    const next = sorted[i + 1]?.step ?? spanSteps;
+    const next = nextStep[i] ?? spanSteps;
     const mid = event.step + (next - event.step) / 2;
     if (Number.isInteger(mid) && mid > event.step && mid < spanSteps) {
       out.push({ ...event, step: mid, velocity: event.velocity * ADDED_NOTE_VELOCITY });
     }
-  }
-  return out;
+  });
+  return out.sort((a, b) => a.step - b.step);
 }
 var ADDED_NOTE_VELOCITY = 0.75;
 function halfTime(events, spanSteps = BAR_STEPS) {
   assertSpanSteps(spanSteps);
-  return assertGridEvents(events).map((event) => ({ ...event, step: event.step * 2 })).filter((event) => event.step < spanSteps);
+  return halfTimeFigure(assertGridEvents(events), spanSteps);
+}
+function halfTimeFigure(figure, spanSteps) {
+  return figure.map((event) => ({ ...event, step: event.step * 2 })).filter((event) => event.step < spanSteps);
 }
 function doubleTime(events, spanSteps = BAR_STEPS) {
   assertSpanSteps(spanSteps);
-  assertGridEvents(events);
+  return doubleTimeFigure(assertGridEvents(events), spanSteps);
+}
+function doubleTimeFigure(figure, spanSteps) {
   const merged = /* @__PURE__ */ new Map();
   const place = (event, step, velocity) => {
-    const key = `${streamOf(event)}@${step}`;
+    const key = positionKey(event, step);
     const held = merged.get(key);
     if (held === void 0 || velocity > held.velocity) {
       merged.set(key, { ...event, step, velocity });
     }
   };
-  for (const event of events) {
-    const step = Math.round(event.step / 2);
+  for (const event of figure) {
+    const step = halvedStep(event.step);
     place(event, step, event.velocity);
     const repeated = step + spanSteps / 2;
     if (repeated < spanSteps) {
@@ -845,14 +879,17 @@ function syncopate(events, amount, draw, ...path) {
   const dial = asked === void 0 ? amount : asked.amount;
   const signature = meterAt(0, toMeterData(asked?.ts ?? FIGURE_TS, "ts"));
   assertRange(dial, 0, 1, "syncopate amount");
-  const occupied = new Set(figure.map((event) => `${streamOf(event)}@${event.step}`));
+  return syncopateFigure(figure, dial, signature, sampler, path);
+}
+function syncopateFigure(figure, dial, ts, sampler, path) {
+  const occupied = new Set(figure.map((event) => positionKey(event, event.step)));
   const out = [...figure];
   for (const event of figure) {
     const anticipated = event.step - 1;
-    if (stepWeight(event.step, signature) < 2 || anticipated < 1 || occupied.has(`${streamOf(event)}@${anticipated}`)) {
+    if (stepWeight(event.step, ts) < 2 || anticipated < 1 || occupied.has(positionKey(event, anticipated))) {
       continue;
     }
-    if (!sampler.prob(dial, ...path, "syncopate", event.step)) {
+    if (!sampler.prob(dial, ...path, "syncopate", ...drawKey(event))) {
       continue;
     }
     out.push({ ...event, step: anticipated, velocity: event.velocity * ADDED_NOTE_VELOCITY });
@@ -865,35 +902,47 @@ function ornamentBy(events, isOrnament, amount, draw, ...path) {
   const sampler = assertDraw(draw);
   assertSeedPath(path);
   assertRange(amount, 0, 1, "ornament amount");
+  return ornamentFigure(figure, marks, amount, sampler, path);
+}
+function ornamentFigure(figure, marks, amount, sampler, path) {
   return figure.filter(
-    (event) => !marks(event) || sampler.prob(amount, ...path, "ornament", event.step)
+    (event) => !marks(event) || sampler.prob(amount, ...path, "ornament", ...drawKey(event))
   );
 }
 var NEUTRAL_RHYTHMIC = 0.5;
 function deform(events, opts, draw, ...path) {
   const figure = assertGridEvents(events);
   const asked = assertRecord(opts, "opts");
-  assertDraw(draw);
+  const sampler = assertDraw(draw);
   assertSeedPath(path);
   const spanSteps = assertSpanSteps(asked.spanSteps === void 0 ? BAR_STEPS : asked.spanSteps);
-  const ts = asked.ts ?? FIGURE_TS;
-  let out = asked.rate === "half" ? halfTime(figure, spanSteps) : asked.rate === "double" ? doubleTime(figure, spanSteps) : [...figure];
-  if (asked.rhythmic !== void 0) {
-    const rhythmic = assertRange(asked.rhythmic, 0, 1, "complexity rhythmic");
-    if (rhythmic < NEUTRAL_RHYTHMIC) {
-      out = thin(out, (NEUTRAL_RHYTHMIC - rhythmic) / NEUTRAL_RHYTHMIC, ts);
-    } else if (rhythmic > NEUTRAL_RHYTHMIC) {
-      out = syncopate(
-        out,
-        { amount: (rhythmic - NEUTRAL_RHYTHMIC) / NEUTRAL_RHYTHMIC, ts },
-        draw,
-        ...path
-      );
-    }
+  return deformFigure(figure, spanSteps, resolveDials(asked), sampler, path);
+}
+function resolveDials(asked) {
+  const rate = assertOneOf(asked.rate ?? "straight", FIGURE_RATES, "rate");
+  const rhythmic = asked.rhythmic === void 0 ? void 0 : assertRange(asked.rhythmic, 0, 1, "complexity rhythmic");
+  const ts = meterAt(0, toMeterData(asked.ts ?? FIGURE_TS, "ts"));
+  const ornament2 = asked.ornament === void 0 ? void 0 : assertRange(asked.ornament, 0, 1, "ornament amount");
+  const isOrnament = asked.isOrnament ? assertFunction(asked.isOrnament, "opts.isOrnament") : void 0;
+  return { rate, rhythmic, ts, ornament: ornament2, isOrnament };
+}
+function deformFigure(figure, spanSteps, dials, sampler, path) {
+  let out = dials.rate === "half" ? halfTimeFigure(figure, spanSteps) : dials.rate === "double" ? doubleTimeFigure(figure, spanSteps) : [...figure];
+  const { rhythmic } = dials;
+  if (rhythmic !== void 0 && rhythmic < NEUTRAL_RHYTHMIC) {
+    out = thinFigure(out, (NEUTRAL_RHYTHMIC - rhythmic) / NEUTRAL_RHYTHMIC, dials.ts);
+  } else if (rhythmic !== void 0 && rhythmic > NEUTRAL_RHYTHMIC) {
+    out = syncopateFigure(
+      out,
+      (rhythmic - NEUTRAL_RHYTHMIC) / NEUTRAL_RHYTHMIC,
+      dials.ts,
+      sampler,
+      path
+    );
   }
-  if (asked.ornament !== void 0 && asked.isOrnament) {
-    const isOrnament = assertFunction(asked.isOrnament, "opts.isOrnament");
-    out = ornamentBy(out, (event) => isOrnament(event), asked.ornament, draw, ...path);
+  const { ornament: ornament2, isOrnament } = dials;
+  if (ornament2 !== void 0 && isOrnament !== void 0) {
+    out = ornamentFigure(out, (event) => isOrnament(event), ornament2, sampler, path);
   }
   return out.sort((a, b) => a.step - b.step);
 }
@@ -1010,6 +1059,32 @@ function isLickMaterial(material) {
   const candidate = material;
   return typeof candidate === "object" && candidate !== null && typeof candidate.lengthSteps === "number" && Array.isArray(candidate.notes);
 }
+function assertLickMaterial(material, label) {
+  material.notes.forEach((given, index) => {
+    const name = `${label} notes[${index}]`;
+    const lickNote = assertRecord(given, name);
+    assertDegree(lickNote.degree, `${name}.degree`);
+    assertFiniteNumber(lickNote.step, `${name}.step`);
+    assertFiniteNumber(lickNote.velocity, `${name}.velocity`);
+    if (lickNote.alter !== void 0) {
+      assertInteger(lickNote.alter, `${name}.alter`);
+    }
+    if (lickNote.lengthSteps !== void 0) {
+      assertFiniteNumber(lickNote.lengthSteps, `${name}.lengthSteps`);
+    }
+    if (lickNote.articulation !== void 0) {
+      assertOneOf(lickNote.articulation, ARTICULATIONS, `${name}.articulation`);
+    }
+    for (const field of ["voice", "limb"]) {
+      const value = lickNote[field];
+      if (value !== void 0 && typeof value !== "string") {
+        throw new InvalidInputError(
+          `${name}.${field} must be a string; received ${describeRejected(value)}`
+        );
+      }
+    }
+  });
+}
 function note(degree, step, velocity, extra) {
   return { degree, step, velocity, ...extra };
 }
@@ -1237,10 +1312,11 @@ function placeLicks(timeline, key, opts) {
   const supplied = asked.difficulty === void 0 ? void 0 : assertDifficulty(asked.difficulty, "lick difficulty");
   const difficulty = resolved.difficulty ?? supplied;
   const { instrument, low } = bassRegister(resolved.instrument("bass"), asked.instrument, octave);
-  const dictionary = mergeVocabulary(
-    BASS_LICKS,
-    vocabularyOfKind(resolved.vocabulary, isLickMaterial)
-  );
+  const callerLicks = vocabularyOfKind(resolved.vocabulary, isLickMaterial);
+  callerLicks.forEach((entry, index) => {
+    assertLickMaterial(entry.material, `lick vocabulary[${index}]`);
+  });
+  const dictionary = mergeVocabulary(BASS_LICKS, callerLicks);
   const playable = instrument === void 0 ? {} : { articulations: instrument.articulations };
   const raw = [];
   for (let index = 0; index < segments.length; index += 1) {
@@ -1672,9 +1748,10 @@ function imitate(lead, opts) {
     let offset = 0;
     if (invert) {
       if (tonal) {
-        const here = scaleLadderPosition(pitch, key);
-        pitch = scaleLadderPitch(2 * scaleLadderPosition(pivot, key).rung - here.rung, key);
-        offset = -here.offset;
+        const axis = scaleLadderPosition(pivot, key);
+        const here = scaleLadderPosition(pitch - axis.offset, key);
+        pitch = scaleLadderPitch(2 * axis.rung - here.rung, key);
+        offset = axis.offset - here.offset;
       } else {
         pitch = 2 * pivot - pitch;
       }
@@ -1880,7 +1957,7 @@ function generateCounterMelody(opts) {
     throw new InvalidInputError("countermelody needs a timeline or a chordAt callback");
   }
   const chordChangeBeats = timeline === void 0 ? opts.chordChangeBeats ?? [] : timeline.segments.flatMap((segment) => [segment.startBeat, segment.endBeat]);
-  const register = opts.register ?? "below";
+  const register = assertOneOf(opts.register ?? "below", ["above", "below"], "register");
   assertNoteEvents(opts.melody, "countermelody melody", { allowNonPositiveDuration: true });
   const melody = createNoteEventIndex(soundingNotesOnly(opts.melody), {
     tieBreak: register === "below" ? "highest" : "lowest"
@@ -2113,13 +2190,14 @@ function denser(level) {
   }
   return "sixteenth";
 }
+var LEVEL_ORDER = ["quarter", "eighth", "sixteenth"];
 function hiHatStep(level) {
   if (level === "sixteenth") {
     return 0.25;
   }
   return level === "eighth" ? 0.5 : 1;
 }
-function getHiHatLevel(section, style, rhythmic, bpm, draw, difficulty, bar2) {
+function getHiHatBar(section, style, rhythmic, bpm, draw, difficulty, bar2) {
   const allow16th = bpm < HH_16TH_BPM_THRESHOLD;
   let base = "eighth";
   let dialed = true;
@@ -2159,22 +2237,41 @@ function getHiHatLevel(section, style, rhythmic, bpm, draw, difficulty, bar2) {
         break;
     }
   }
+  const playable = (proposed) => {
+    let level2 = !allow16th && proposed === "sixteenth" ? "eighth" : proposed;
+    while (level2 !== "quarter" && !sustainsStrokes(hiHatStep(level2), bpm, difficulty)) {
+      level2 = sparser(level2);
+    }
+    return level2;
+  };
   let level = base;
+  let thinnedUpTo = Number.NEGATIVE_INFINITY;
+  let filledAbove = Number.POSITIVE_INFINITY;
   if (dialed) {
-    if (draw.at("hhThin", bar2) >= 2 * rhythmic) {
+    const thin2 = draw.at("hhThin", bar2);
+    if (thin2 >= 2 * rhythmic) {
       level = sparser(level);
     }
-    if (draw.at("hhFill", bar2) < 2 * rhythmic - 1) {
+    const fill2 = draw.at("hhFill", bar2);
+    if (fill2 < 2 * rhythmic - 1) {
       level = denser(level);
     }
+    thinnedUpTo = thin2 / 2;
+    filledAbove = (fill2 + 1) / 2;
   }
-  if (!allow16th && level === "sixteenth") {
-    level = "eighth";
-  }
-  while (level !== "quarter" && !sustainsStrokes(hiHatStep(level), bpm, difficulty)) {
-    level = sparser(level);
-  }
-  return level;
+  const rank = (candidate) => LEVEL_ORDER.indexOf(candidate);
+  const sparsest = rank(playable(dialed ? sparser(base) : base));
+  const middle = rank(playable(base));
+  const densest = rank(playable(dialed ? denser(base) : base));
+  const entryOf = (grid) => sparsest >= rank(grid) ? Number.NEGATIVE_INFINITY : middle >= rank(grid) ? thinnedUpTo : densest >= rank(grid) ? filledAbove : Number.POSITIVE_INFINITY;
+  return {
+    level: playable(level),
+    entries: {
+      quarter: entryOf("quarter"),
+      eighth: entryOf("eighth"),
+      sixteenth: entryOf("sixteenth")
+    }
+  };
 }
 function hiHatVelocityMultiplier(sixteenth, jitter) {
   switch (sixteenth) {
@@ -2385,11 +2482,12 @@ function generateKickForBeat(ctx, sec, kick) {
   const sixteenths = kick.length / 4;
   for (let step = 0; step < sixteenths; step += 1) {
     const index = ctx.beat * sixteenths + step;
-    if (!kick[index]) {
+    const entry = kick[index];
+    if (entry === void 0) {
       continue;
     }
     if (step === 0) {
-      ctx.track.add(GM.BD, ctx.beatTick, EIGHTH, ctx.velocity);
+      ctx.track.add(GM.BD, ctx.beatTick, EIGHTH, ctx.velocity, void 0, entry);
       continue;
     }
     const offBeat = step % 2 === 1;
@@ -2397,7 +2495,7 @@ function generateKickForBeat(ctx, sec, kick) {
       continue;
     }
     const tick = swing16(ctx.beatTick + step * SIXTEENTH, sec, ctx.swingAmount);
-    ctx.track.add(GM.BD, tick, offBeat ? SIXTEENTH : EIGHTH, ctx.velocity * 0.85);
+    ctx.track.add(GM.BD, tick, offBeat ? SIXTEENTH : EIGHTH, ctx.velocity * 0.85, void 0, entry);
   }
 }
 function roleBackbeatWeight(role) {
@@ -2450,16 +2548,19 @@ function generateGhostNotesForBeat(ctx, sec) {
     return;
   }
   const positions = selectGhostPositions(sec.ghostMood);
-  let ghostProb = leanedBy(getGhostDensity(sec.ghostMood, ctx.section, ctx.bpm), sec.ornament);
+  const ghostDensity = getGhostDensity(sec.ghostMood, ctx.section, ctx.bpm);
+  let ghostProb = leanedBy(ghostDensity, sec.ornament);
   if (sec.ghostBoost) {
     ghostProb = Math.min(1, ghostProb * 1.4);
   }
   for (const pos of positions) {
     const sixteenthInBeat = pos === "e" ? 1 : 3;
     const posProb = getGhostProbabilityAtPosition(ctx.beat, sixteenthInBeat, leadIns);
-    if (!ctx.draw.prob(ghostProb * posProb, "ghost", ctx.bar, ctx.beat, pos)) {
+    const at2 = ctx.draw.at("ghost", ctx.bar, ctx.beat, pos);
+    if (!(at2 < ghostProb * posProb)) {
       continue;
     }
+    const entry = sec.ornamentFollowsRhythmic ? at2 / (posProb * (sec.ghostBoost ? 1.4 : 1) * ghostDensity) - 0.5 : Number.NEGATIVE_INFINITY;
     const variation = ctx.draw.float(0.85, 1.15, "ghostVelocity", ctx.bar, ctx.beat, pos);
     const ghostBase = getGhostVelocity(ctx.section, ctx.beat / 2);
     let ghostVel = ctx.velocity * ghostBase * variation;
@@ -2468,7 +2569,7 @@ function generateGhostNotesForBeat(ctx, sec) {
     }
     const offset = pos === "e" ? SIXTEENTH : 3 * SIXTEENTH;
     const tick = swing16(ctx.beatTick + offset, sec, ctx.swingAmount);
-    ctx.track.add(GM.SD, tick, SIXTEENTH, ghostVel);
+    ctx.track.add(GM.SD, tick, SIXTEENTH, ghostVel, void 0, entry);
   }
 }
 function generatePreChorusBuildup(ctx, sec, isSectionLastBar) {
@@ -2526,17 +2627,25 @@ function generateHiHatForBeat(ctx, sec) {
   const allowsOpenHiHat = sec.role !== "ambient" && sec.role !== "minimal";
   const isDynamicOpen = ctx.barHasOpenHh && ctx.beat === ctx.openHhBeat && !usesOffbeatOpenHiHat(sec.style);
   const dm = sec.densityMult;
+  const beatEntry = ctx.section === "intro" && ctx.beat !== 0 ? ctx.hhEntries.eighth : ctx.hhEntries.quarter;
   if (ctx.hhLevel === "quarter") {
     if (ctx.section === "intro" && ctx.beat !== 0) {
       return;
     }
     const hhVel = Math.max(20, ctx.velocity * dm * 0.75 * typeMult);
     if (allowsOpenHiHat && isDynamicOpen) {
-      ctx.track.add(GM.OHH, ctx.beatTick, EIGHTH, hhVel + OHH_VEL_BOOST);
+      ctx.track.add(GM.OHH, ctx.beatTick, EIGHTH, hhVel + OHH_VEL_BOOST, void 0, beatEntry);
     } else if (allowsOpenHiHat && opensOnDownbeat(ctx, sec)) {
-      ctx.track.add(hiHatNote("open"), ctx.beatTick, EIGHTH, Math.max(20, hhVel * 1.1));
+      ctx.track.add(
+        hiHatNote("open"),
+        ctx.beatTick,
+        EIGHTH,
+        Math.max(20, hhVel * 1.1),
+        void 0,
+        beatEntry
+      );
     } else {
-      ctx.track.add(hhInstrument, ctx.beatTick, EIGHTH, hhVel);
+      ctx.track.add(hhInstrument, ctx.beatTick, EIGHTH, hhVel, void 0, beatEntry);
     }
     return;
   }
@@ -2546,22 +2655,37 @@ function generateHiHatForBeat(ctx, sec) {
       if (eighth === 1) {
         hhTick = swing16(hhTick, sec, ctx.swingAmount);
       }
+      const entry = eighth === 0 ? beatEntry : ctx.hhEntries.eighth;
       if (ctx.section === "intro" && eighth === 1) {
         if (sec.useFootHh && ctx.beat % 2 === 0) {
-          ctx.track.add(GM.FHH, hhTick, EIGHTH, footHiHatVelocity(ctx.draw, ctx.bar, ctx.beat));
+          ctx.track.add(
+            GM.FHH,
+            hhTick,
+            EIGHTH,
+            footHiHatVelocity(ctx.draw, ctx.bar, ctx.beat),
+            void 0,
+            entry
+          );
         }
         continue;
       }
       const hhVel = Math.max(20, ctx.velocity * dm * typeMult * (eighth === 0 ? 0.9 : 0.65));
       if (isDynamicOpen && allowsOpenHiHat && eighth === 0) {
-        ctx.track.add(GM.OHH, hhTick, EIGHTH, hhVel + OHH_VEL_BOOST);
+        ctx.track.add(GM.OHH, hhTick, EIGHTH, hhVel + OHH_VEL_BOOST, void 0, entry);
         continue;
       }
       const useOpen = eighth === 0 ? opensOnDownbeat(ctx, sec) : opensOffbeat(ctx, sec);
       if (useOpen && allowsOpenHiHat) {
-        ctx.track.add(hiHatNote("open"), hhTick, EIGHTH, Math.max(20, hhVel * 1.1));
+        ctx.track.add(
+          hiHatNote("open"),
+          hhTick,
+          EIGHTH,
+          Math.max(20, hhVel * 1.1),
+          void 0,
+          entry
+        );
       } else {
-        ctx.track.add(hhInstrument, hhTick, EIGHTH / 2, hhVel);
+        ctx.track.add(hhInstrument, hhTick, EIGHTH / 2, hhVel, void 0, entry);
       }
     }
     return;
@@ -2576,26 +2700,41 @@ function generateHiHatForBeat(ctx, sec) {
       ctx.draw.float(0.95, 1.05, "hatVelocity", ctx.bar, ctx.beat, sixteenth)
     );
     const hhVel = Math.max(20, ctx.velocity * dm * typeMult * metricVel);
+    const entry = sixteenth === 0 ? beatEntry : sixteenth === 2 ? ctx.hhEntries.eighth : ctx.hhEntries.sixteenth;
     if (isDynamicOpen && allowsOpenHiHat && sixteenth === 0) {
-      ctx.track.add(GM.OHH, hhTick, SIXTEENTH, hhVel + OHH_VEL_BOOST);
+      ctx.track.add(GM.OHH, hhTick, SIXTEENTH, hhVel + OHH_VEL_BOOST, void 0, entry);
       continue;
     }
     if (allowsOpenHiHat && sixteenth === 0 && opensOnDownbeat(ctx, sec)) {
-      ctx.track.add(hiHatNote("open"), hhTick, SIXTEENTH, Math.max(20, hhVel * 1.1));
+      ctx.track.add(
+        hiHatNote("open"),
+        hhTick,
+        SIXTEENTH,
+        Math.max(20, hhVel * 1.1),
+        void 0,
+        entry
+      );
       continue;
     }
     if (allowsOpenHiHat && sixteenth === 2 && opensOffbeat(ctx, sec)) {
-      ctx.track.add(hiHatNote("open"), hhTick, SIXTEENTH, Math.max(20, hhVel * 1.1));
+      ctx.track.add(
+        hiHatNote("open"),
+        hhTick,
+        SIXTEENTH,
+        Math.max(20, hhVel * 1.1),
+        void 0,
+        entry
+      );
       continue;
     }
     if (allowsOpenHiHat && ctx.beat === 3 && sixteenth === 3) {
       const openProb = Math.max(0.1, Math.min(0.4, 30 / ctx.bpm));
       if (ctx.draw.prob(openProb, "openHat", ctx.bar, ctx.beat, sixteenth)) {
-        ctx.track.add(GM.OHH, hhTick, SIXTEENTH, Math.max(20, hhVel * 1.2));
+        ctx.track.add(GM.OHH, hhTick, SIXTEENTH, Math.max(20, hhVel * 1.2), void 0, entry);
         continue;
       }
     }
-    ctx.track.add(hhInstrument, hhTick, SIXTEENTH / 2, hhVel);
+    ctx.track.add(hhInstrument, hhTick, SIXTEENTH / 2, hhVel, void 0, entry);
   }
 }
 
@@ -2622,7 +2761,7 @@ function bjorklund(pulses, steps) {
   }
   let head = Array.from({ length: pulses }, () => [true]);
   let remainder = Array.from({ length: steps - pulses }, () => [false]);
-  while (remainder.length > 1) {
+  do {
     const count = Math.min(head.length, remainder.length);
     const next = [];
     for (let i = 0; i < count; i += 1) {
@@ -2630,7 +2769,7 @@ function bjorklund(pulses, steps) {
     }
     remainder = head.length > count ? head.slice(count) : remainder.slice(count);
     head = next;
-  }
+  } while (remainder.length > 1);
   return [...head.flat(), ...remainder.flat()];
 }
 
@@ -2650,6 +2789,7 @@ var FILL_TYPES = Object.freeze([
   "flamsAndDrags",
   "halfTimeFill"
 ]);
+var FILL_VELOCITY_BASES = Object.freeze(["fill", "accent"]);
 var S = SIXTEENTH;
 var E = EIGHTH;
 function fill(scale, offset) {
@@ -2773,6 +2913,29 @@ var FILL_ARCHETYPES = deepFreeze({
 function isFillArchetype(material) {
   return typeof material === "object" && material !== null && Array.isArray(material.atBeat);
 }
+function assertFillArchetype(material, label) {
+  material.atBeat.forEach((beat, beatIndex) => {
+    const strokes = assertArray(beat, `${label} atBeat[${beatIndex}]`);
+    strokes.forEach((given, strokeIndex) => {
+      const name = `${label} atBeat[${beatIndex}][${strokeIndex}]`;
+      const stroke = assertRecord(given, name);
+      assertMidiPitch(stroke.voice, `${name}.voice`);
+      assertFiniteNumber(stroke.offset, `${name}.offset`);
+      assertFiniteNumber(stroke.duration, `${name}.duration`);
+      const velocity = assertRecord(stroke.velocity, `${name}.velocity`);
+      assertOneOf(velocity.base, FILL_VELOCITY_BASES, `${name}.velocity.base`);
+      if (velocity.scale !== void 0) {
+        assertFiniteNumber(velocity.scale, `${name}.velocity.scale`);
+      }
+      if (velocity.offset !== void 0) {
+        assertRange(velocity.offset, -127, 127, `${name}.velocity.offset`);
+      }
+      if (stroke.articulation !== void 0) {
+        assertOneOf(stroke.articulation, ARTICULATIONS, `${name}.articulation`);
+      }
+    });
+  });
+}
 function fillArchetypeFor(id, supplied) {
   return supplied?.get(id) ?? FILL_ARCHETYPES[id];
 }
@@ -2947,6 +3110,8 @@ var HitList = class {
   hits = [];
   /** Voices already struck at each quantized beat. */
   #onsets = /* @__PURE__ */ new Map();
+  /** The rhythmic-dial setting each onset enters at, by onset key; absent is always. */
+  #entries = /* @__PURE__ */ new Map();
   /**
    * Append a hit, clamping velocity and dropping non-positive positions.
    *
@@ -2954,12 +3119,23 @@ var HitList = class {
    * sounds once however many voices ask for it, and a second entry at the same
    * pitch and position is a note-on a reader answers with no note-off, heard as
    * a hung or cut stroke rather than as a louder one.
+   *
+   * `entry` is the rhythmic-dial setting above which the stroke sounds, for a
+   * stroke the dial adds; a stroke asked for twice sounds from the lower one.
    */
-  add(pitch, startBeat, durationBeat, velocity, articulation) {
+  add(pitch, startBeat, durationBeat, velocity, articulation, entry = Number.NEGATIVE_INFINITY) {
     const beat = Math.max(0, startBeat);
+    const key = onsetKey(pitch, beat);
+    const held = this.#entries.get(key);
     if (this.hasOnset(pitch, beat)) {
+      if (held !== void 0 && entry < held) {
+        this.#entries.set(key, entry);
+      }
       return;
     }
+    if (entry !== Number.NEGATIVE_INFINITY) {
+      this.#entries.set(key, entry);
+    }
     const hit2 = {
       pitch,
       startBeat: beat,
@@ -2977,6 +3153,13 @@ var HitList = class {
       this.#onsets.set(beatSlot(beat), /* @__PURE__ */ new Set([pitch]));
     }
   }
+  /**
+   * The rhythmic-dial setting above which a written stroke sounds: minus
+   * infinity for one that sounds at every setting.
+   */
+  entryOf(pitch, startBeat) {
+    return this.#entries.get(onsetKey(pitch, startBeat)) ?? Number.NEGATIVE_INFINITY;
+  }
   /** Whether a hit of this pitch already starts exactly at `startBeat`. */
   hasOnset(pitch, startBeat) {
     return this.#onsets.get(beatSlot(startBeat))?.has(pitch) ?? false;
@@ -3073,17 +3256,14 @@ var KICK_FIGURES = deepFreeze({
   ],
   standard: DEFAULT_FIGURE
 });
-function emptyPattern() {
-  return Array.from({ length: KICK_STEPS }, () => false);
-}
 function isInPreChorusLift(section, bar2, sectionBars, nextIsChorus) {
   if (section !== "b" || !nextIsChorus || sectionBars < 3) {
     return false;
   }
   return bar2 >= sectionBars - 2;
 }
-function realiseKickFigure(figure, section, bar2, draw, rhythmic) {
-  const pattern = emptyPattern();
+function realiseKickEntries(figure, section, bar2, draw, rhythmic) {
+  const entries = Array.from({ length: KICK_STEPS }, () => void 0);
   for (const slot of figure) {
     if (slot.step < 0 || slot.step >= KICK_STEPS) {
       continue;
@@ -3095,19 +3275,23 @@ function realiseKickFigure(figure, section, bar2, draw, rhythmic) {
       continue;
     }
     if (slot.probability === void 0) {
-      pattern[slot.step] = true;
+      entries[slot.step] = Number.NEGATIVE_INFINITY;
       continue;
     }
-    if (draw.prob(leanedBy(slot.probability, rhythmic), "kick", bar2, slot.slot ?? slot.step)) {
-      pattern[slot.step] = true;
+    const at2 = draw.at("kick", bar2, slot.slot ?? slot.step);
+    if (at2 < leanedBy(slot.probability, rhythmic)) {
+      entries[slot.step] = Math.min(
+        entries[slot.step] ?? Number.POSITIVE_INFINITY,
+        at2 / slot.probability - 0.5
+      );
     }
   }
-  return pattern;
+  return entries;
 }
-function getKickPattern(section, style, bar2, draw, rhythmic) {
+function getKickEntries(section, style, bar2, draw, rhythmic) {
   const own = KICK_FIGURES[style] ?? DEFAULT_FIGURE;
   const figure = section === "outro" ? [...OUTRO_FIGURE, ...statedSlots(own)] : own;
-  return realiseKickFigure(figure, section, bar2, draw, rhythmic);
+  return realiseKickEntries(figure, section, bar2, draw, rhythmic);
 }
 
 // src/generate/drums/percussion.ts
@@ -3144,6 +3328,8 @@ var PERC_TABLE = [
   /* rock */
   [F, F, F, [false, false, true], F, F, F, F, [false, false, true]]
 ];
+var SHAKER_SIXTEENTH_CURVE = [0.75, 0.45, 0.6, 0.45];
+var SHAKER_EIGHTH_CURVE = [0.75, 0.55];
 function getPercussionConfig(mood, section) {
   const row = PERC_TABLE[mood] ?? PERC_TABLE[1 /* Standard */];
   const act = row?.[sectionIndex(section)] ?? F;
@@ -3168,10 +3354,11 @@ function generateAuxPercussionForBar(track, barStart, config, role, densityMult,
   if (config.shaker) {
     const use16th = config.shaker16th && bpm < HH_16TH_BPM_THRESHOLD && sustainsStrokes(SIXTEENTH, bpm, sec.difficulty);
     if (use16th) {
-      const velCurve = [0.75, 0.45, 0.6, 0.45];
+      const velCurve = SHAKER_SIXTEENTH_CURVE;
       for (let beat = 0; beat < barBeats; beat += 1) {
         for (let sub = 0; sub < 4; sub += 1) {
-          if (sub % 2 === 1 && !draw.prob(sec.rhythmic, "shaker16", barStart, beat, sub)) {
+          const entry = sub % 2 === 1 ? draw.at("shaker16", barStart, beat, sub) : Number.NEGATIVE_INFINITY;
+          if (!(entry < sec.rhythmic)) {
             continue;
           }
           const raw = 80 * (velCurve[sub] ?? 0.5) * densityMult * draw.float(0.9, 1.1, "shaker", barStart, beat, sub);
@@ -3179,12 +3366,14 @@ function generateAuxPercussionForBar(track, barStart, config, role, densityMult,
             GM.SHAKER,
             swing16(barStart + beat + sub * SIXTEENTH, sec, swingAmount),
             SIXTEENTH,
-            Math.max(25, Math.min(85, raw))
+            Math.max(25, Math.min(85, raw)),
+            void 0,
+            entry
           );
         }
       }
     } else {
-      const velCurve = [0.75, 0.55];
+      const velCurve = SHAKER_EIGHTH_CURVE;
       for (let beat = 0; beat < barBeats; beat += 1) {
         for (let sub = 0; sub < 2; sub += 1) {
           const raw = 80 * (velCurve[sub] ?? 0.6) * densityMult * draw.float(0.9, 1.1, "shaker", barStart, beat, sub);
@@ -3470,6 +3659,7 @@ function placeDrumPattern(opts) {
     assertRange(opts.velocity, 1, 127, "drum pattern velocity");
   }
   const feel = opts.feel === void 0 ? "straight" : assertOneOf(opts.feel, DRUM_FEELS, "feel");
+  const rate = assertOneOf(opts.rate ?? "straight", FIGURE_RATES, "rate");
   const resolved = resolveContext(opts.ctx);
   const bpm = resolved.bpm ?? DEFAULT_BPM2;
   const draw = resolved.part("drums");
@@ -3515,7 +3705,7 @@ function placeDrumPattern(opts) {
         ...resolved.rhythmic === void 0 ? {} : { rhythmic: resolved.rhythmic },
         ...resolved.ornament === void 0 ? {} : { ornament: resolved.ornament },
         isOrnament: (stroke) => stroke.articulation === "ghost",
-        rate: opts.rate ?? "straight",
+        rate,
         spanSteps: entry.material.steps,
         // The dials rank the figure's positions against the bar it is written
         // in, which is the bar this call is placing it in.
@@ -3602,6 +3792,7 @@ function generateDrums(opts) {
     densityMult,
     rhythmic,
     ornament: ornamentDial,
+    ornamentFollowsRhythmic: resolved.ornament === void 0,
     difficulty,
     ghostBoost: mapping.ghostBoost,
     useRide: shouldUseRideForSection(section, style),
@@ -3617,10 +3808,15 @@ function generateDrums(opts) {
   const percMood = percMoodCategory(style);
   const nextSection = opts.nextSection ? mapSection(opts.nextSection) : section;
   const nextEnergy = sectionEnergy(nextSection);
-  const callerFillEntries = selectVocabulary(
-    vocabularyOfKind(resolved.vocabulary, isFillArchetype),
-    { section: publicSection, bpm, difficulty }
-  );
+  const suppliedFills = vocabularyOfKind(resolved.vocabulary, isFillArchetype);
+  suppliedFills.forEach((entry, index) => {
+    assertFillArchetype(entry.material, `drum fill vocabulary[${index}]`);
+  });
+  const callerFillEntries = selectVocabulary(suppliedFills, {
+    section: publicSection,
+    bpm,
+    difficulty
+  });
   const callerFills = new Map(callerFillEntries.map((entry) => [entry.id, entry.material]));
   const callerFillIds = callerFillEntries.map((entry) => entry.id);
   const euclidSteps = opts.euclideanKick?.steps ?? 16;
@@ -3631,7 +3827,7 @@ function generateDrums(opts) {
   for (let bar2 = 0; bar2 < opts.bars; bar2 += 1) {
     const barStart = bar2 * barBeats;
     const isLastBar = bar2 === opts.bars - 1;
-    const hhLevel = getHiHatLevel(section, style, rhythmic, bpm, draw, difficulty, bar2);
+    const hiHat = getHiHatBar(section, style, rhythmic, bpm, draw, difficulty, bar2);
     if (bar2 === 0 && section === "chorus") {
       track.add(GM.CRASH, barStart, 0.5, 100 * densityMult);
     }
@@ -3643,10 +3839,10 @@ function generateDrums(opts) {
     }
     let kick;
     if (!euclidKick && reuseSectionKick) {
-      sectionKick ??= getKickPattern(section, style, 0, draw, rhythmic);
+      sectionKick ??= getKickEntries(section, style, 0, draw, rhythmic);
       kick = sectionKick;
     } else if (!euclidKick) {
-      kick = getKickPattern(section, style, bar2, draw, rhythmic);
+      kick = getKickEntries(section, style, bar2, draw, rhythmic);
     }
     const inLift = isInPreChorusLift(section, bar2, opts.bars, nextSection === "chorus");
     let currentFill = FILL_ARCHETYPES.snareRoll;
@@ -3702,7 +3898,8 @@ function generateDrums(opts) {
         swingAmount,
         barHasOpenHh,
         openHhBeat: openHhBeatIndex,
-        hhLevel,
+        hhLevel: hiHat.level,
+        hhEntries: hiHat.entries,
         draw
       };
       if (playMainVoices) {
@@ -3763,24 +3960,44 @@ function generateDrums(opts) {
   const endBeat = opts.bars * barBeats;
   const kit = resolved.instrument("drums");
   const written = track.hits.filter((hit2) => hit2.startBeat < endBeat && playableOn(kit, hit2.pitch)).sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
-  return underCeiling(written, bpm, difficulty, exemptOnsets);
+  return underCeiling(written, bpm, difficulty, exemptOnsets, track);
 }
-function underCeiling(hits, bpm, difficulty, exempt) {
+function underCeiling(hits, bpm, difficulty, exempt, track) {
   if (difficulty === void 0) {
     return [...hits];
   }
-  const lastOnset = /* @__PURE__ */ new Map();
-  const kept = [];
-  for (const hit2 of hits) {
-    const previous = lastOnset.get(hit2.pitch);
-    const reachable = previous === void 0 || exempt.has(onsetKey(hit2.pitch, hit2.startBeat)) || sustainsStrokes(hit2.startBeat - previous, bpm, difficulty);
+  const entries = hits.map((hit2) => track.entryOf(hit2.pitch, hit2.startBeat));
+  const order = hits.map((_, index) => index).sort((a, b) => {
+    const left = entries[a];
+    const right = entries[b];
+    return left < right ? -1 : left > right ? 1 : a - b;
+  });
+  const keptBeats = /* @__PURE__ */ new Map();
+  const kept = hits.map(() => false);
+  for (const index of order) {
+    const hit2 = hits[index];
+    const beats = keptBeats.get(hit2.pitch) ?? [];
+    let at2 = 0;
+    let end = beats.length;
+    while (at2 < end) {
+      const mid = at2 + end >>> 1;
+      if (beats[mid] > hit2.startBeat) {
+        end = mid;
+      } else {
+        at2 = mid + 1;
+      }
+    }
+    const previous = beats[at2 - 1];
+    const next = beats[at2];
+    const reachable = exempt.has(onsetKey(hit2.pitch, hit2.startBeat)) || (previous === void 0 || sustainsStrokes(hit2.startBeat - previous, bpm, difficulty)) && (next === void 0 || sustainsStrokes(next - hit2.startBeat, bpm, difficulty));
     if (!reachable) {
       continue;
     }
-    kept.push(hit2);
-    lastOnset.set(hit2.pitch, hit2.startBeat);
+    kept[index] = true;
+    beats.splice(at2, 0, hit2.startBeat);
+    keptBeats.set(hit2.pitch, beats);
   }
-  return kept;
+  return hits.filter((_, index) => kept[index]);
 }
 function playableOn(kit, pitch) {
   return kit === void 0 || canSound(kit, pitch);
@@ -3799,7 +4016,7 @@ var MIN_VELOCITY = 1;
 var MAX_VELOCITY = 127;
 function humanize(events, opts = {}) {
   const asked = assertOptions(opts, "opts");
-  const ts = meterAt(0, toMeterData(asked.ts ?? DEFAULT_TS3, "ts"));
+  const meter = toMeterData(asked.ts ?? DEFAULT_TS3, "ts");
   assertNoteEvents(events, "humanize events", { allowNonPositiveDuration: true });
   const sounding2 = dropSilentNotes(events);
   const timing = asked.timing ?? DEFAULT_TIMING;
@@ -3815,7 +4032,7 @@ function humanize(events, opts = {}) {
   return sounding2.map((event) => {
     const timingOffset = draw.float(-timing, timing, "timing", event.startBeat, event.pitch);
     const startBeat = event.startBeat + timingOffset;
-    const weight = metricWeight(event.startBeat, ts);
+    const weight = metricWeight(event.startBeat, meter);
     const accentBoost = weight / MAX_METRIC_WEIGHT * accent2;
     const velocityOffset = draw.float(
       -velocityJitter,
@@ -3829,6 +4046,21 @@ function humanize(events, opts = {}) {
     return { ...event, startBeat, velocity };
   });
 }
+function grooveSignature(ts) {
+  const meter = toMeterData(ts, "ts");
+  if (!Array.isArray(meter)) {
+    return meter;
+  }
+  const opening = meterAt(0, meter);
+  for (const change of meter) {
+    if (change.ts.numerator !== opening.numerator || change.ts.denominator !== opening.denominator) {
+      throw new InvalidInputError(
+        `groove time signature must be one signature throughout; received ${change.ts.numerator}/${change.ts.denominator} at beat ${change.startBeat} in a meter that is ${opening.numerator}/${opening.denominator} at beat 0`
+      );
+    }
+  }
+  return opening;
+}
 function quantizeToGrid(beat, barBeats, subdivision, slotsPerBar) {
   const barIndex = Math.floor(beat / barBeats);
   const modBeat = beat - barIndex * barBeats;
@@ -3844,7 +4076,7 @@ function quantizeToGrid(beat, barBeats, subdivision, slotsPerBar) {
   };
 }
 function extractGrooveTemplate(events, ts, subdivision = DEFAULT_GROOVE_SUBDIVISION) {
-  const meter = meterAt(0, toMeterData(ts, "ts"));
+  const meter = grooveSignature(ts);
   assertNoteEvents(events, "groove source events", { allowNonPositiveDuration: true });
   assertPositiveInt(subdivision, "groove subdivision");
   const barBeats = beatsPerBar(meter);
@@ -3885,7 +4117,7 @@ function extractGrooveTemplate(events, ts, subdivision = DEFAULT_GROOVE_SUBDIVIS
   return { subdivision, slotsPerBar, slots, ts: meter };
 }
 function applyGrooveTemplate(events, template, ts) {
-  const meter = meterAt(0, toMeterData(ts, "ts"));
+  const meter = grooveSignature(ts);
   assertNoteEvents(events, "groove target events", { allowNonPositiveDuration: true });
   assertPositiveInt(template.subdivision, "template subdivision");
   assertPositiveInt(template.slotsPerBar, "template slotsPerBar");
@@ -3949,15 +4181,27 @@ function classifyMelodyTones(melody, ts) {
   const meter = meterAt(0, toMeterData(ts, "ts"));
   assertNoteEvents(melody, "melody notes", { allowNonPositiveDuration: true });
   const pulse2 = pulseBeats(meter);
-  return melody.map((_, index) => {
-    const role = roleOfNote(melody, index, meter, pulse2);
-    return { noteIndex: index, role, ornamental: role !== "structural" };
+  const sounding2 = new Set(soundingIndices(melody));
+  const line = canonicalNoteOrder(melody).filter((index) => sounding2.has(index));
+  const roles = melody.map(() => "structural");
+  line.forEach((index, position) => {
+    const before = line[position - 1];
+    const after = line[position + 1];
+    roles[index] = roleOfNote(
+      before === void 0 ? void 0 : melody[before],
+      melody[index],
+      after === void 0 ? void 0 : melody[after],
+      meter,
+      pulse2
+    );
   });
+  return roles.map((role, index) => ({
+    noteIndex: index,
+    role,
+    ornamental: role !== "structural"
+  }));
 }
-function roleOfNote(melody, index, ts, pulse2) {
-  const note2 = melody[index];
-  const prev = melody[index - 1];
-  const next = melody[index + 1];
+function roleOfNote(prev, note2, next, ts, pulse2) {
   if (!note2 || !prev || !next) {
     return "structural";
   }
@@ -4013,13 +4257,11 @@ var DEFAULT_PLACEMENT = {
 };
 var DEFAULT_METER = { numerator: 4, denominator: 4 };
 var TIE_BREAK_JITTER2 = 1e-6;
-function cadencesThroughRaisedSeventh(key) {
-  return isMinorKey(key) && scaleSystemOf(key) === "common-practice";
-}
 function isKeyTone(pitch, key) {
   return isScaleTone(pitch, key) || cadencesThroughRaisedSeventh(key) && pitchClassOf(pitch) === leadingTonePcOf(key);
 }
 function inferKey(melody) {
+  const line = inOnsetOrder(melody);
   let best = majorKey(0);
   let bestScore = Number.NEGATIVE_INFINITY;
   const candidates = [];
@@ -4029,7 +4271,7 @@ function inferKey(melody) {
   for (const key of candidates) {
     const tonic = pitchClassOf(key.rootPc);
     let score = 0;
-    for (const n of melody) {
+    for (const n of line) {
       const w = Math.max(0.25, n.durationBeat);
       const pc = pitchClassOf(n.pitch);
       if (isKeyTone(n.pitch, key)) {
@@ -4046,6 +4288,12 @@ function inferKey(melody) {
   }
   return best;
 }
+function inOnsetOrder(melody) {
+  return canonicalNoteOrder(melody).flatMap((index) => {
+    const note2 = melody[index];
+    return note2 === void 0 ? [] : [note2];
+  });
+}
 
 // src/generate/harmonize/cost.ts
 var NON_CHORD_TONE_STRONG = 4;
@@ -4342,15 +4590,23 @@ function buildSegments(spans, melody, ts, grid, phraseEnds, budget) {
 }
 
 // src/generate/harmonize/candidates.ts
-var ROOT_WEIGHT_BY_SEMITONE = [0, 0.9, 0.3, 0.45, 0.45, 0.15, 0.9, 0.1, 0.3, 0.3, 0.3, 0.9];
+var ROOT_WEIGHT_BY_SEMITONE = [
+  0,
+  0.9,
+  0.3,
+  0.45,
+  0.45,
+  0.15,
+  0.9,
+  0.1,
+  0.3,
+  0.3,
+  0.3,
+  0.9
+];
 var UNSTABLE_TRIAD = 0.9;
-var UNSTABLE_QUALITIES = /* @__PURE__ */ new Set([
-  "dim",
-  "aug",
-  "dim7",
-  "m7b5",
-  "aug7"
-]);
+var UNSTABLE_QUALITY_NAMES = ["dim", "aug", "dim7", "m7b5", "aug7"];
+var UNSTABLE_QUALITIES = new Set(UNSTABLE_QUALITY_NAMES);
 function vocabularyBase(rootPc, quality, tonicPc) {
   const above = (pitchClassOf(rootPc) - tonicPc + 12) % 12;
   const root = ROOT_WEIGHT_BY_SEMITONE[above] ?? UNSTABLE_TRIAD;
@@ -4364,7 +4620,7 @@ function secondaryDominantTargets(key) {
     tonicizableDegrees(key).map((degree) => [degree.degreeNumber, degree])
   );
   return SECONDARY_DOMINANT_TARGETS.map((degree) => tonicizable.get(degree)).filter(
-    (degree) => degree !== void 0
+    (degree) => degree !== void 0 && !isNativeDominantSeventh(degree.rootPc + 7, key)
   );
 }
 var SECONDARY_DOMINANT_ENTRY_ORDER = [5, 6, 2, 4];
@@ -4379,13 +4635,14 @@ var REHARMONIZE_DIAL = {
 function admittedCount(fraction, size) {
   return Math.max(0, Math.min(size, Math.ceil(fraction * size)));
 }
-function buildCandidates(key, harmonic) {
+function buildCandidates(keyLike, harmonic) {
+  const { scale: key, tonic } = resolveKey(keyLike);
   const tonicPc = pitchClassOf(key.rootPc);
   const frame = heptatonicFrameOf(key);
   const tones = scaleTonesInDegreeOrder(frame);
   const candidates = tones.map((rootPc, index) => {
     const degree = index + 1;
-    const quality = diatonicTriad(degree, frame).quality;
+    const quality = diatonicTriad(degree, { ...frame, tonic }).quality;
     return {
       rootPc,
       quality,
@@ -4429,7 +4686,7 @@ function buildCandidates(key, harmonic) {
   const parallelTones = scaleTonesInDegreeOrder(parallel);
   const borrowed = [];
   for (let degree = 1; degree <= parallelTones.length; degree += 1) {
-    const chord = diatonicTriad(degree, parallel);
+    const chord = diatonicTriad(degree, { ...parallel, tonic });
     if (!isDiatonic(chord, key)) {
       borrowed.push(chord);
     }
@@ -4475,11 +4732,11 @@ function harmonizeMelody(opts) {
     allowNonPositiveDuration: true,
     budget: opts.budget
   });
-  const phraseEnds = opts.phraseEnds ?? [];
+  const phraseEnds = assertArray(opts.phraseEnds ?? [], "harmonize phrase ends");
   for (const end of phraseEnds) {
     assertFiniteNumber(end, "harmonize phrase end");
   }
-  const soundingMelody = soundingNotesOnly(opts.melody);
+  const soundingMelody = inOnsetOrder(soundingNotesOnly(opts.melody));
   const ts = meterAt(0, toMeterData(opts.ts ?? DEFAULT_METER, "ts"));
   assertTimeSignature(ts);
   const requestedKey = opts.key ?? "infer";
@@ -4487,7 +4744,10 @@ function harmonizeMelody(opts) {
     requestedKey === "infer" ? inferKey(soundingMelody) : requestedKey
   );
   const key = resolvedKey.scale;
-  const placement = opts.placement ?? DEFAULT_PLACEMENT;
+  const placement = assertRecord(
+    opts.placement ?? DEFAULT_PLACEMENT,
+    "harmonize placement"
+  );
   const ctx = resolveContext(opts.ctx);
   const reharmonize = assertOneOf(
     opts.reharmonize ?? "diatonic",
@@ -4498,7 +4758,7 @@ function harmonizeMelody(opts) {
   if (soundingMelody.length === 0) {
     return { transposeSemitones: 0, key: resolvedKey, chords: [], melodyRoles: [] };
   }
-  const candidates = buildCandidates(key, harmonic);
+  const candidates = buildCandidates(resolvedKey, harmonic);
   const candAt = (i) => candidates[i] ?? FALLBACK;
   const draw = ctx.part("harmony");
   const jitter = candidates.map((_, index) => draw.at("jitter", index) * TIE_BREAK_JITTER2);
@@ -4549,6 +4809,7 @@ function harmonizeMelody(opts) {
     "harmonization placement search",
     opts.budget
   );
+  let bestFit = Number.POSITIVE_INFINITY;
   let bestCost = Number.POSITIVE_INFINITY;
   let bestTs = 0;
   let bestPath = [];
@@ -4563,8 +4824,10 @@ function harmonizeMelody(opts) {
       closingSegments,
       articulatedSegments
     );
-    const total = cost + keyFitCost(shifted, key) + tessituraCost(shifted);
-    if (total < bestCost) {
+    const fit = keyFitCost(shifted, key);
+    const total = cost + tessituraCost(shifted);
+    if (fit < bestFit || fit === bestFit && total < bestCost) {
+      bestFit = fit;
       bestCost = total;
       bestTs = shift;
       bestPath = path;
@@ -4699,7 +4962,11 @@ function contourOffsets(contour, count) {
 }
 function generateMotif(opts) {
   assertRecord(opts, "motif options");
-  const contour = opts.contour ?? "arch";
+  const contour = assertOneOf(
+    opts.contour ?? "arch",
+    ["arch", "ascending", "descending", "wave"],
+    "motif contour"
+  );
   const bars = assertPositiveInt(opts.bars, "motif bars");
   const barBeats = beatsPerBar(meterAt(0, toMeterData(opts.ts ?? DEFAULT_TS4, "ts")));
   const totalBeats = bars * barBeats;
@@ -4846,6 +5113,10 @@ function developMotif(cell, timeline, key, bars, ts) {
   if (span <= 0) {
     return inTimeOrder(cell);
   }
+  const line = canonicalNoteOrder(cellNotes).flatMap((index) => {
+    const note2 = cellNotes[index];
+    return note2 === void 0 ? [] : [note2];
+  });
   const tileSpan = Math.max(span, MIN_TILE_SPAN);
   const tileCount = Math.ceil(totalBeats / tileSpan);
   assertGenerationBudget(tileCount * cellNotes.length, "developed motif notes");
@@ -4853,7 +5124,7 @@ function developMotif(cell, timeline, key, bars, ts) {
     const offset = k * tileSpan;
     const taken = /* @__PURE__ */ new Map();
     let previous;
-    for (const n of cellNotes) {
+    for (const n of line) {
       const startBeat = offset + (n.startBeat - origin);
       if (startBeat >= totalBeats) {
         continue;
@@ -4866,7 +5137,11 @@ function developMotif(cell, timeline, key, bars, ts) {
       const pitch = developedPitch(n.pitch, allows, direction, taken);
       taken.set(pitch, n.pitch);
       previous = n.pitch;
-      out.push({ pitch, startBeat, durationBeat: n.durationBeat });
+      out.push({
+        pitch,
+        startBeat,
+        durationBeat: Math.min(n.durationBeat, totalBeats - startBeat)
+      });
     }
   }
   return inTimeOrder({ notes: out });
@@ -4878,6 +5153,13 @@ function positionClass(beat, meters) {
   const weight = metricWeight(beat, meters);
   return weight >= STRONG_WEIGHT ? "strong" : weight > 0 ? "weak" : "off";
 }
+function finalDownbeat(phrase, meters) {
+  let downbeat = barStartBeat(phrase.startBeat, meters);
+  while (downbeat + beatsPerBarAt(downbeat, meters) < phrase.endBeat - BEAT_EPS) {
+    downbeat += beatsPerBarAt(downbeat, meters);
+  }
+  return Math.max(downbeat, phrase.startBeat);
+}
 
 // src/generate/plan/types.ts
 var COMPOSITION_PLAN_VERSION = 1;
@@ -5158,7 +5440,7 @@ function planChordTimeline(plan) {
 }
 
 // src/generate/plan/harmony.ts
-var HARMONY_OK_KINDS = /* @__PURE__ */ new Set([
+var HARMONY_OK_KIND_NAMES = [
   "chordTone",
   "tension",
   "suspension",
@@ -5166,7 +5448,8 @@ var HARMONY_OK_KINDS = /* @__PURE__ */ new Set([
   "anticipation",
   "passing",
   "neighbor"
-]);
+];
+var HARMONY_OK_KINDS = new Set(HARMONY_OK_KIND_NAMES);
 var CADENCE_DEGREES = {
   authentic: [1, 3],
   plagal: [1, 3],
@@ -5189,8 +5472,13 @@ function cadencePitchClasses(plan, timeline, cadence, beat) {
     return chord === null ? null : chordPitchClasses(chord);
   }
   const entry = plan.harmony.find((chord) => beat >= chord.startBeat && beat < chord.endBeat);
-  const tones = scaleTonesInDegreeOrder(scaleOf(plan.keys[entry?.key ?? 0]));
-  return CADENCE_DEGREES[cadence].map((degree) => tones[degree - 1]).filter((pc) => pc !== void 0);
+  const scale = scaleOf(plan.keys[entry?.key ?? 0]);
+  const tones = scaleTonesInDegreeOrder(scale);
+  const raised = cadencesThroughRaisedSeventh(scale);
+  return CADENCE_DEGREES[cadence].map((degree) => {
+    const tone = tones[degree - 1];
+    return raised && degree === 7 && tone !== void 0 ? leadingTonePcOf(scale) : tone;
+  }).filter((pc) => pc !== void 0);
 }
 function planHarmonyMisfits(plan, timeline = planChordTimeline(plan)) {
   const keyAt = planKeyAt(plan);
@@ -5206,7 +5494,8 @@ function planHarmonyMisfits(plan, timeline = planChordTimeline(plan)) {
       if (kinds.some((kind) => HARMONY_OK_KINDS.has(kind))) {
         return null;
       }
-      return position === "weak" && isScaleTone(note2.pitch, scaleAt2(note2.startBeat)) ? null : kinds;
+      const lenient = position === "weak" || timeline.at(note2.startBeat) === null;
+      return lenient && isScaleTone(note2.pitch, scaleAt2(note2.startBeat)) ? null : kinds;
     });
   };
 }
@@ -5341,16 +5630,19 @@ function stretched(cell, timeRatio) {
 function shaped(cell, relation) {
   switch (relation.kind) {
     case "repetition":
-    case "tonalTransposition":
       return cell;
     case "transposition":
+    case "tonalTransposition":
       return stretched(cell, relation.timeRatio);
     case "inversion":
       return stretched(transformMotif(cell, "invert"), relation.timeRatio);
     case "retrograde":
-      return transformMotif(cell, "retrograde");
+      return stretched(transformMotif(cell, "retrograde"), relation.timeRatio);
     case "retrogradeInversion":
-      return transformMotif(transformMotif(cell, "invert"), "retrograde");
+      return stretched(
+        transformMotif(transformMotif(cell, "invert"), "retrograde"),
+        relation.timeRatio
+      );
     case "augmentation":
       return transformMotif(cell, "augment", relation.timeRatio);
     case "diminution":
@@ -5625,6 +5917,7 @@ function onsetSlots(scene, startBeat, endBeat) {
         slots.push(beat);
       }
     }
+    assertGenerationBudget(slots.length, "melody onset slots", scene.budget);
     bar2 = barEnd;
   }
   return slots;
@@ -5765,15 +6058,6 @@ function lineBefore(scene, index, beat) {
   }
   return line.sort((a, b) => a.startBeat - b.startBeat);
 }
-function finalDownbeat(scene, index) {
-  const phrase = scene.plan.phrases[index];
-  const { meters } = scene.plan;
-  let downbeat = barStartBeat(phrase.startBeat, meters);
-  while (downbeat + beatsPerBarAt(downbeat, meters) < phrase.endBeat - BEAT_EPS) {
-    downbeat += beatsPerBarAt(downbeat, meters);
-  }
-  return Math.max(downbeat, phrase.startBeat);
-}
 function heldNoteIndex(scene, index, line, downbeat) {
   const phrase = scene.plan.phrases[index];
   const sounding2 = line.findIndex(
@@ -5904,7 +6188,7 @@ function generateMelody(plan, opts) {
   const melody = [];
   plan.phrases.forEach((_, index) => {
     const line = phraseLine(scene, index);
-    const downbeat = finalDownbeat(scene, index);
+    const downbeat = finalDownbeat(plan.phrases[index], plan.meters);
     let held = heldNoteIndex(scene, index, line, downbeat);
     if (held >= 0) {
       line.length = held + 1;
@@ -5940,8 +6224,8 @@ var DEFAULT_VELOCITY2 = 80;
 var MIN_VELOCITY2 = 1;
 var MAX_VELOCITY2 = 127;
 var SLIDE_MIN_SEMITONES = 1;
-function eligible(style, note2, previous, next, ts) {
-  const strong = isStrongBeat(note2.startBeat, ts);
+function eligible(style, note2, previous, next, meter) {
+  const strong = isStrongBeat(note2.startBeat, meter);
   switch (style) {
     case "ghost":
       return !strong;
@@ -5949,7 +6233,7 @@ function eligible(style, note2, previous, next, ts) {
     case "accent":
       return strong;
     case "drag":
-      return !strong && next !== void 0 && isStrongBeat(next.startBeat, ts);
+      return !strong && next !== void 0 && isStrongBeat(next.startBeat, meter);
     case "slide":
       return previous !== void 0 && Math.abs(note2.pitch - previous.pitch) >= SLIDE_MIN_SEMITONES;
   }
@@ -5977,8 +6261,7 @@ function ornament(notes, opts = {}) {
   const asked = assertOptions(opts, "opts");
   assertNoteEvents(notes, "ornament notes", { allowNonPositiveDuration: true });
   const style = assertOneOf(asked.style ?? DEFAULT_STYLE2, ORNAMENT_STYLES, "ornament style");
-  const ts = meterAt(0, toMeterData(asked.ts ?? DEFAULT_TS5, "ts"));
-  assertTimeSignature(ts);
+  const meter = toMeterData(asked.ts ?? DEFAULT_TS5, "ts");
   if (asked.amount !== void 0) {
     assertRange(asked.amount, 0, 1, "ornament amount");
   }
@@ -5992,7 +6275,7 @@ function ornament(notes, opts = {}) {
   const gaps = strokeGaps(ordered);
   return sounding2.map((note2) => {
     const decorated = { ...note2 };
-    if (note2.articulation !== void 0 || !eligible(style, note2, previousOf.get(note2), nextOf.get(note2), ts)) {
+    if (note2.articulation !== void 0 || !eligible(style, note2, previousOf.get(note2), nextOf.get(note2), meter)) {
       return decorated;
     }
     if (!sustainsStrokes(gaps.get(note2) ?? Number.POSITIVE_INFINITY, ctx.bpm, ctx.difficulty)) {
@@ -6108,13 +6391,14 @@ function rejectSuppliedRng(ctx) {
   }
 }
 function plannedKeys(profile, requested) {
-  const regions = profile.harmony.keys.map(
-    ({ key }) => ({
-      scale: { ...key.scale },
-      tonic: { ...key.tonic },
-      variant: key.variant
-    })
-  );
+  const regions = profile.harmony.keys.map(({ key }) => {
+    const resolved = resolveKey(key);
+    return {
+      scale: { ...resolved.scale },
+      tonic: { ...resolved.tonic },
+      variant: resolved.variant
+    };
+  });
   const home = regions[0];
   if (requested === void 0) {
     return regions;
@@ -6364,11 +6648,23 @@ function selectedDerivation(graph, parentEdge, selectedAt, node) {
   }
   return { from: null, relation: null };
 }
+function functionTriad(fn, degree, key) {
+  if (fn === "dominant" && cadencesThroughRaisedSeventh(key.scale)) {
+    if (degree === 5) {
+      return makeChord(pitchClassOf(key.scale.rootPc + 7), "maj");
+    }
+    if (degree === 7) {
+      return makeChord(leadingTonePcOf(key.scale), "dim");
+    }
+  }
+  return diatonicTriad(degree, key);
+}
 function functionCandidates(fn, key) {
   if (scaleTonesInDegreeOrder(key).length !== HEPTATONIC_DEGREES) {
     return null;
   }
-  return FUNCTION_DEGREES[fn].map((degree) => chordToRoman(diatonicTriad(degree, key), key));
+  const numerals = FUNCTION_DEGREES[fn].map((degree) => functionTriad(fn, degree, key)).filter((chord) => functionOf(chord, key) === fn).map((chord) => chordToRoman(chord, key));
+  return numerals.length === 0 ? null : numerals;
 }
 function plannedHarmony(profile, keys, preserve, draw) {
   const chords = profile.harmony.chords;
@@ -6448,6 +6744,11 @@ function deriveCompositionPlan(reference, opts) {
   };
   const sections = plannedSections(profile, preserve.form, draw);
   const shapeWeight = preserve.registerShape;
+  const phraseBars = profile.form.phrases.reduce(
+    (bars, phrase) => bars + barIndexAt(phrase.endBeat, profile.meters) - barIndexAt(phrase.startBeat, profile.meters),
+    0
+  );
+  assertGenerationBudget(phraseBars, "plan phrase bars");
   const spans = plannedPhraseSpans(profile, sections, preserve.phraseLengths, draw);
   const phrases = spans.map((span) => {
     const melody = profile.form.phrases[span.source]?.melody ?? null;
@@ -6633,7 +6934,7 @@ function harmonyViolations(melody, plan, timeline, lines) {
       const derived = plan.motifs.some(
         (motif) => motif.from !== null && note2.startBeat >= motif.startBeat - BEAT_EPS && note2.startBeat < motif.endBeat - BEAT_EPS
       );
-      const strong = positionClass(note2.startBeat, plan.meters) === "strong";
+      const strong = positionClass(note2.startBeat, plan.meters) === "strong" && timeline.at(note2.startBeat) !== null;
       violations.push({
         kind: "harmony",
         severity: derived ? "warning" : "error",
@@ -6651,7 +6952,16 @@ function notesInRange(melody, startBeat, endBeat) {
     (note2) => note2.startBeat >= startBeat - BEAT_EPS && note2.startBeat < endBeat - BEAT_EPS
   );
 }
-function replayLevel(source, derived, statement, sourceEnd, plan, key, closing) {
+function keptEnd(statement, melody, plan) {
+  const phrase = phraseAt(plan, statement.startBeat);
+  if (phrase === void 0) {
+    return statement.endBeat;
+  }
+  const downbeat = finalDownbeat(phrase, plan.meters);
+  const held = notesInRange(melody, downbeat, phrase.endBeat).length === 1;
+  return held ? Math.min(statement.endBeat, downbeat) : statement.endBeat;
+}
+function replayLevel(source, derived, statement, sourceEnd, derivedEnd, sourceCut, plan, key, closing) {
   const relation = statement.relation;
   const planned = relation.kind === "tonalTransposition" ? relation.degrees ?? 0 : relation.semitones;
   const { low, high } = plan.phrases[statement.phrase].register;
@@ -6668,23 +6978,24 @@ function replayLevel(source, derived, statement, sourceEnd, plan, key, closing)
   const replays = relationLevels(relation.kind).map((level) => {
     const notes = clipStatement(
       replayAt(cell, relation, level, statement.startBeat, key),
-      statement.endBeat
+      derivedEnd
     );
     return { level, notes, outside: notes.filter((note2) => outside(note2.pitch)).length };
   });
   const fewestOutside = Math.min(...replays.map((replay) => replay.outside));
   let best = null;
   for (const { level, notes: expected, outside: away } of replays) {
-    if (expected.length !== derived.length) {
+    const compared = sourceCut ? derived.slice(0, expected.length) : derived;
+    if (expected.length !== compared.length) {
       continue;
     }
     let forced = 0;
     let holds = true;
     for (let i = 0; holds && i < expected.length; i += 1) {
       const want = expected[i];
-      const got = derived[i];
+      const got = compared[i];
       if (i > 0) {
-        const gap = got.startBeat - derived[i - 1].startBeat;
+        const gap = got.startBeat - compared[i - 1].startBeat;
         holds = Math.abs(gap - (want.startBeat - expected[i - 1].startBeat)) <= BEAT_EPS;
       }
       if (!holds || got.pitch === want.pitch) {
@@ -6715,6 +7026,11 @@ function motifDerivationViolations(melody, plan, closing) {
     const derivedNotes = notesInRange(melody, statement.startBeat, statement.endBeat);
     const relation = statement.relation;
     const rationale = `the statement at beat ${statement.startBeat} does not derive from its source the way the plan names`;
+    const sourceKept = keptEnd(source, melody, plan);
+    const derivedKept = keptEnd(statement, melody, plan);
+    if (sourceKept <= source.startBeat + BEAT_EPS || derivedKept <= statement.startBeat + BEAT_EPS) {
+      continue;
+    }
     if (sourceNotes.length === 0 || derivedNotes.length === 0) {
       errors.push({
         kind: "motifDerivation",
@@ -6726,8 +7042,17 @@ function motifDerivationViolations(melody, plan, closing) {
       });
       continue;
     }
+    const sourceCut = sourceKept < source.endBeat - BEAT_EPS;
+    const derivedCut = derivedKept < statement.endBeat - BEAT_EPS;
     if (relation === null) {
-      const similarity = melodicSimilarity(sourceNotes, derivedNotes);
+      const sourceEnd = derivedCut ? Math.min(sourceKept, source.startBeat + derivedKept - statement.startBeat) : sourceKept;
+      const derivedEnd = sourceCut ? Math.min(derivedKept, statement.startBeat + sourceKept - source.startBeat) : derivedKept;
+      const sourceLine = notesInRange(melody, source.startBeat, sourceEnd);
+      const derivedLine = notesInRange(melody, statement.startBeat, derivedEnd);
+      if (sourceLine.length === 0 || derivedLine.length === 0) {
+        continue;
+      }
+      const similarity = melodicSimilarity(sourceLine, derivedLine);
       if (similarity < DEFAULT_VARIATION_THRESHOLD) {
         errors.push({
           kind: "motifDerivation",
@@ -6740,11 +7065,18 @@ function motifDerivationViolations(melody, plan, closing) {
       }
       continue;
     }
+    const kept = notesInRange(melody, source.startBeat, sourceKept);
+    const backward = relation.kind === "retrograde" || relation.kind === "retrogradeInversion";
+    if (kept.length === 0 || sourceCut && backward) {
+      continue;
+    }
     const replay = replayLevel(
-      sourceNotes,
-      derivedNotes,
+      kept,
+      notesInRange(melody, statement.startBeat, derivedKept),
       statement,
-      source.endBeat,
+      sourceKept,
+      derivedKept,
+      sourceCut,
       plan,
       scaleOf(keyAt(statement.startBeat)),
       closing
@@ -7122,12 +7454,12 @@ function degreeToRootPc(degree, key) {
   const offset = BORROWED_OFFSET[degree] ?? 0;
   return ((key.rootPc % 12 + offset) % 12 + 12) % 12;
 }
-function autoQuality(degree, key, harmonicDominant) {
+function autoQuality(degree, key, tonic, harmonicDominant) {
   if (degree >= 1 && degree <= 7) {
-    if (harmonicDominant && isMinorKey(key) && degree === 5) {
+    if (harmonicDominant && cadencesThroughRaisedSeventh(key) && degree === 5) {
       return "maj";
     }
-    return diatonicTriad(degree, heptatonicFrameOf(key)).quality;
+    return diatonicTriad(degree, { ...heptatonicFrameOf(key), tonic }).quality;
   }
   if (degree === 14) {
     return "dim";
@@ -7137,11 +7469,11 @@ function autoQuality(degree, key, harmonicDominant) {
   }
   return "maj";
 }
-function resolveCycle(degrees, key, ext, harmonicDominant) {
+function resolveCycle(degrees, key, tonic, ext, harmonicDominant) {
   const steps = degrees.map((degree) => {
     const step = {
       rootPc: degreeToRootPc(degree, key),
-      quality: ext !== void 0 && ext !== "auto" ? ext : autoQuality(degree, key, harmonicDominant)
+      quality: ext !== void 0 && ext !== "auto" ? ext : autoQuality(degree, key, tonic, harmonicDominant)
     };
     if (degree >= 1 && degree <= 7) {
       step.degree = degree;
@@ -7174,17 +7506,22 @@ function generateProgression(opts) {
   assertRecord(opts, "progression options");
   assertPositiveInt(opts.bars, "progression bars");
   assertGenerationBudget(opts.bars, "progression chords");
-  const key = toKeyScale(opts.key);
+  const { scale: key, tonic } = resolveKey(opts.key);
   const ctx = resolveContext(opts.ctx);
   let preset;
   if (opts.preset !== void 0) {
-    if (opts.preset.degrees.length === 0) {
+    const custom = assertRecord(
+      opts.preset,
+      "progression preset"
+    );
+    const degrees = assertArray(custom.degrees, "progression preset degrees");
+    if (degrees.length === 0) {
       throw new InvalidInputError("progression preset must name at least one degree");
     }
     preset = {
-      id: opts.preset.id ?? "custom",
-      name: opts.preset.name ?? "Custom",
-      degrees: opts.preset.degrees.map((degree, index) => {
+      id: custom.id ?? "custom",
+      name: custom.name ?? "Custom",
+      degrees: degrees.map((degree, index) => {
         assertDegree(degree, `progression preset degrees[${index}]`);
         const supported = degree >= 1 && degree <= 7 || Object.values(BORROWED_DEGREES).includes(degree);
         if (!supported) {
@@ -7194,8 +7531,12 @@ function generateProgression(opts) {
         }
         return degree;
       }),
-      functional: opts.preset.functional ?? "loop",
-      styles: opts.preset.styles ?? [opts.style]
+      functional: assertOneOf(
+        custom.functional ?? "loop",
+        ["loop", "tensionBuild", "cadenceStrong", "stable"],
+        "progression preset functional"
+      ),
+      styles: custom.styles ?? [opts.style]
     };
   }
   if (preset === void 0 && opts.presetId !== void 0) {
@@ -7209,6 +7550,7 @@ function generateProgression(opts) {
   const cycle = resolveCycle(
     preset?.degrees ?? [0],
     key,
+    tonic,
     ext,
     preset?.functional === "cadenceStrong"
   );
@@ -7241,10 +7583,11 @@ function generateProgression(opts) {
       const domRoot = (next.rootPc + 7) % 12;
       const targetsTonic = (next.rootPc - tonicPc + 12) % 12 === 0;
       const isLastTonicStatement = cur.rootPc === tonicPc && tonicStatements <= 1;
-      const alreadySecondary = cur.rootPc === domRoot && cur.quality === "dom7";
+      const alreadySecondary = cur.rootPc === domRoot && soundsDominantSeventh(makeChord(cur.rootPc, cur.quality));
+      const isNativeDominant = isNativeDominantSeventh(domRoot, key);
       const isResolutionTarget = chords[i - 1]?.secondaryDominant === true;
       const takesNoDominant = !canBeTonicized(next, tonicizable);
-      if (targetsTonic || isLastTonicStatement || alreadySecondary || isResolutionTarget || takesNoDominant) {
+      if (targetsTonic || isLastTonicStatement || alreadySecondary || isResolutionTarget || takesNoDominant || isNativeDominant) {
         continue;
       }
       if (draw.prob(harmonic, "reharmonize", i)) {
@@ -7282,11 +7625,11 @@ function triadQualityOf(chord) {
   }
   return hasThird;
 }
-function diatonicTriadsOf(key) {
+function diatonicTriadsOf(key, tonic) {
   const degrees = scaleTonesInDegreeOrder(key).length;
   const triads = [];
   for (let degree = 1; degree <= degrees; degree += 1) {
-    triads.push(diatonicTriad(degree, key));
+    triads.push(diatonicTriad(degree, { ...key, tonic }));
   }
   return triads;
 }
@@ -7320,10 +7663,22 @@ function tritoneSubstituteRoot(dominant, tonic, key) {
   const resolution = spellPitchClass(pitchClassOf(dominant.rootPc + 5), tonic, key);
   return transposeNote(resolution, 1);
 }
+var MEDIANT_THIRDS = {
+  3: "m3",
+  4: "M3",
+  8: "-M3",
+  9: "-m3"
+};
+function mediantRoot(source, offset, tonic, key) {
+  const hint = source.rootSpelling;
+  const root = hint !== void 0 && noteToPitchClass(hint) === pitchClassOf(source.rootPc) ? hint : spellPitchClass(source.rootPc, tonic, key);
+  return transposeByInterval(bareSpelling(root), MEDIANT_THIRDS[offset]);
+}
 function substituteChord(chord, key, opts) {
   assertOptions(opts, "opts");
   const source = toChordData(chord);
-  const { scale, tonic } = resolveKey(key);
+  const resolved = resolveKey(key);
+  const { scale, tonic } = resolved;
   const originalTriad = chordPitchClasses(makeChord(source.rootPc, triadQualityOf(source)));
   const candidates = [];
   if (soundsDominantSeventh(source)) {
@@ -7333,24 +7688,27 @@ function substituteChord(chord, key, opts) {
       type: "tritone"
     });
   }
-  for (const triad of diatonicTriadsOf(scale)) {
+  for (const triad of diatonicTriadsOf(scale, tonic)) {
     const offset = pitchClassOf(triad.rootPc - source.rootPc);
     if (THIRD_OFFSETS.includes(offset) && commonToneCount(originalTriad, chordPitchClasses(triad)) === 2) {
       candidates.push({ chord: spelledInKey(triad, tonic, scale), type: "relative" });
     }
   }
-  const targetFunction = functionOf(source, scale);
+  const targetFunction = functionOf(source, resolved);
   const parallel = parallelKey(scale);
-  for (const triad of diatonicTriadsOf(parallel)) {
-    if (functionOf(triad, scale) === targetFunction && !isDiatonic(triad, scale)) {
+  for (const triad of diatonicTriadsOf(parallel, tonic)) {
+    if (functionOf(triad, resolved) === targetFunction && !isDiatonic(triad, resolved)) {
       candidates.push({ chord: spelledInKey(triad, tonic, parallel), type: "borrowed" });
     }
   }
   for (const offset of THIRD_OFFSETS) {
     for (const quality of ["maj", "min"]) {
       const mediant = makeChord(pitchClassOf(source.rootPc + offset), quality);
-      if (commonToneCount(originalTriad, chordPitchClasses(mediant)) === 1 && !isDiatonic(mediant, scale)) {
-        candidates.push({ chord: spelledInKey(mediant, tonic, scale), type: "chromaticMediant" });
+      if (commonToneCount(originalTriad, chordPitchClasses(mediant)) === 1 && !isDiatonic(mediant, resolved)) {
+        candidates.push({
+          chord: spelledOnRoot(mediant, mediantRoot(source, offset, tonic, scale), tonic, scale),
+          type: "chromaticMediant"
+        });
       }
     }
   }
@@ -7375,14 +7733,15 @@ function substituteChord(chord, key, opts) {
     results.push({
       chord: candidate.chord,
       type: candidate.type,
-      roman: chordToRoman(candidate.chord, scale),
-      function: functionOf(candidate.chord, scale)
+      roman: chordToRoman(candidate.chord, resolved),
+      function: functionOf(candidate.chord, resolved)
     });
   }
   return results;
 }
 function modalInterchangePalette(key) {
-  const { scale, tonic } = resolveKey(key);
+  const resolved = resolveKey(key);
+  const { scale, tonic } = resolved;
   const palette = [];
   const seen = /* @__PURE__ */ new Set();
   const add = (chord) => {
@@ -7393,18 +7752,18 @@ function modalInterchangePalette(key) {
     seen.add(dedupeKey);
     palette.push({
       chord,
-      roman: chordToRoman(chord, scale),
-      source: borrowedSource(chord, scale)
+      roman: chordToRoman(chord, resolved),
+      source: borrowedSource(chord, resolved)
     });
   };
   const parallel = parallelKey(scale);
-  for (const triad of diatonicTriadsOf(parallel)) {
-    if (!isDiatonic(triad, scale) && borrowedSource(triad, scale) !== null) {
+  for (const triad of diatonicTriadsOf(parallel, tonic)) {
+    if (!isDiatonic(triad, resolved) && borrowedSource(triad, resolved) !== null) {
       add(spelledInKey(triad, tonic, parallel));
     }
   }
   const neapolitan = makeChord(pitchClassOf(scale.rootPc + 1), "maj");
-  if (!isDiatonic(neapolitan, scale)) {
+  if (!isDiatonic(neapolitan, resolved)) {
     add(spelledOnRoot(neapolitan, transposeNote(tonic, 1), tonic, scale));
   }
   return palette;
@@ -7433,12 +7792,13 @@ var DEFAULT_RHYTHM_VELOCITY = 96;
 function rhythmToNoteEvents(events, pitch, velocity = DEFAULT_RHYTHM_VELOCITY) {
   assertMidiPitch(pitch, "pitch");
   assertInteger(velocity, "velocity", 0, 127);
-  return assertArray(events, "events").map((event) => ({
-    pitch,
-    startBeat: event.position,
-    durationBeat: event.duration,
-    velocity
-  }));
+  return assertArray(events, "events").map((given, index) => {
+    const event = assertRecord(given, `events[${index}]`);
+    const bound = Number.MAX_SAFE_INTEGER;
+    assertRange(event.position, -bound, bound, `events[${index}].position`);
+    assertRange(event.duration, -bound, bound, `events[${index}].duration`);
+    return { pitch, startBeat: event.position, durationBeat: event.duration, velocity };
+  });
 }
 var DEFAULT_SUBDIVISION = 2;
 var DEFAULT_DENSITY = 0.5;
@@ -7533,10 +7893,14 @@ export {
   thin,
   double,
   halfTime,
+  halfTimeFigure,
   doubleTime,
+  doubleTimeFigure,
   syncopate,
   ornamentBy,
   deform,
+  resolveDials,
+  deformFigure,
   withinCeiling,
   isLickMaterial,
   BASS_LICKS,
@@ -7588,4 +7952,4 @@ export {
   generateRhythm,
   rhythmDensity
 };
-//# sourceMappingURL=chunk-CPMB7P75.js.map
+//# sourceMappingURL=chunk-FK3DGAIZ.js.map