@libraz/libcantus 1.2.0 → 1.4.0

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

@@ -1,16 +1,39 @@
 import {
+  CADENCE_TYPES,
+  DEFAULT_VARIATION_THRESHOLD,
   HUMANIZE_ADJACENCY,
+  MELODIC_CONTOUR_SHAPES,
+  MOTIF_RELATION_KINDS,
+  RHYTHM_IOI_BINS,
+  analyzeRhythm,
+  analyzeVoice,
   assertChordTimeline,
+  assertReferenceProfile,
+  barSpanOf,
   borrowedSource,
+  chordTimelineFromChords,
   chordToRoman,
+  contourSimilarity,
+  densitySimilarity,
   detectChordBest,
+  durationSimilarity,
   functionOf,
+  ioiBinIndex,
   isDiatonic,
-  isMinorKey,
-  parallelKey
-} from "./chunk-H2KJHBW4.js";
+  keyLookup,
+  melodicSimilarity,
+  onsetSimilarity,
+  parallelKey,
+  phraseMelody,
+  registerSimilarity,
+  rhythmLevel,
+  romanToChord,
+  syncopationSimilarity
+} from "./chunk-FJFULJZE.js";
 import {
+  ALGORITHM_VERSION,
   LIMBS,
+  MIN_ALGORITHM_VERSION,
   canSound,
   createPositionalRng,
   deriveSeed,
@@ -18,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,
@@ -39,6 +66,7 @@ import {
   fifthPcOf,
   heptatonicFrameOf,
   isForbiddenMelodicLeap,
+  isNativeDominantSeventh,
   isScaleTone,
   leadingTonePcOf,
   majorKey,
@@ -50,26 +78,32 @@ import {
   resolveKey,
   scaleLadderPitch,
   scaleLadderPosition,
-  scaleSystemOf,
+  scaleOf,
   scaleTonesInDegreeOrder,
   shiftByScaleDegrees,
   soundsDominantSeventh,
+  spanFromChord,
   spellPitchClass,
   toChordData,
   toKeyScale,
   tonicizableDegrees
-} from "./chunk-RFIBF2RR.js";
+} from "./chunk-H7FVMBUC.js";
 import {
   ARTICULATIONS,
   BEAT_EPS,
   InvalidInputError,
+  NoSolutionError,
+  allocateCandidateTable,
+  allocateChoiceTable,
   assertArray,
   assertDegree,
   assertFiniteNumber,
   assertFiniteSemitones,
+  assertFlag,
   assertFunction,
   assertGenerationBudget,
   assertInteger,
+  assertMeterMap,
   assertMidiPitch,
   assertNoteEvents,
   assertOneOf,
@@ -78,7 +112,10 @@ import {
   assertRange,
   assertRecord,
   assertTimeSignature,
+  barIndexAt,
+  barStartBeat,
   beatsPerBar,
+  beatsPerBarAt,
   clampToMidi,
   describeRejected,
   dropSilentNotes,
@@ -92,10 +129,12 @@ import {
   pulseBeats,
   resolveMeters,
   soundingNotesOnly,
+  spelledInterval,
   toMeterData,
   toSpelledInterval,
+  transposeByInterval,
   transposeNote
-} from "./chunk-AGOVW7U6.js";
+} from "./chunk-YYVXRV3V.js";
 
 // src/generate/context/draw.ts
 var DRAW_METHODS = ["at", "prob", "range", "float"];
@@ -150,7 +189,7 @@ function drawsFrom(rng, ...prefix) {
         );
       }
       assertFiniteNumber(hi - lo, "float span");
-      return lo + at2(...path) * (hi - lo);
+      return scaleUnitDraw(at2(...path), lo, hi);
     }
   };
 }
@@ -375,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");
@@ -536,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) {
@@ -546,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,
@@ -566,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)))
   };
@@ -718,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) => {
@@ -732,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);
@@ -754,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) {
@@ -810,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 });
@@ -830,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);
 }
@@ -975,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 };
 }
@@ -1202,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) {
@@ -1637,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;
       }
@@ -1845,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"
@@ -2078,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;
@@ -2124,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) {
@@ -2350,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;
@@ -2362,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) {
@@ -2415,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;
@@ -2433,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) {
@@ -2491,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;
   }
@@ -2511,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;
@@ -2541,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);
   }
 }
 
@@ -2587,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) {
@@ -2595,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()];
 }
 
@@ -2615,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) {
@@ -2738,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];
 }
@@ -2912,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.
    *
@@ -2919,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,
@@ -2942,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;
@@ -3038,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;
@@ -3060,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
@@ -3109,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;
@@ -3133,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);
@@ -3144,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);
@@ -3435,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");
@@ -3480,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.
@@ -3567,6 +3792,7 @@ function generateDrums(opts) {
     densityMult,
     rhythmic,
     ornament: ornamentDial,
+    ornamentFollowsRhythmic: resolved.ornament === void 0,
     difficulty,
     ghostBoost: mapping.ghostBoost,
     useRide: shouldUseRideForSection(section, style),
@@ -3582,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;
@@ -3596,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);
     }
@@ -3608,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;
@@ -3667,7 +3898,8 @@ function generateDrums(opts) {
         swingAmount,
         barHasOpenHh,
         openHhBeat: openHhBeatIndex,
-        hhLevel,
+        hhLevel: hiHat.level,
+        hhEntries: hiHat.entries,
         draw
       };
       if (playMainVoices) {
@@ -3728,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);
@@ -3764,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;
@@ -3780,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,
@@ -3794,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;
@@ -3809,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);
@@ -3850,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");
@@ -3914,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";
   }
@@ -3978,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 = [];
@@ -3994,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)) {
@@ -4011,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;
@@ -4307,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;
@@ -4329,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];
@@ -4344,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,
@@ -4394,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);
     }
@@ -4440,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";
@@ -4452,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",
@@ -4463,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);
@@ -4514,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 = [];
@@ -4528,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;
@@ -4664,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;
@@ -4811,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");
@@ -4818,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;
@@ -4831,153 +5137,2143 @@ 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 });
 }
 
-// src/generate/ornament/index.ts
-var ORNAMENT_STYLES = Object.freeze(["ghost", "flam", "drag", "slide", "accent"]);
-var DEFAULT_TS5 = { numerator: 4, denominator: 4 };
-var DEFAULT_STYLE2 = "ghost";
-var DEFAULT_AMOUNT = 0.5;
-var GHOST_VELOCITY_SCALE = 0.45;
-var ACCENT_VELOCITY_BOOST = 12;
-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);
-  switch (style) {
-    case "ghost":
-      return !strong;
-    case "flam":
-    case "accent":
-      return strong;
-    case "drag":
-      return !strong && next !== void 0 && isStrongBeat(next.startBeat, ts);
-    case "slide":
-      return previous !== void 0 && Math.abs(note2.pitch - previous.pitch) >= SLIDE_MIN_SEMITONES;
+// src/generate/plan/internal.ts
+var STRONG_WEIGHT = 2;
+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);
 }
-function articulationOf(style) {
-  return style;
+
+// src/generate/plan/types.ts
+var COMPOSITION_PLAN_VERSION = 1;
+function tent(t, apex) {
+  if (t <= apex) {
+    return apex === 0 ? 1 : -1 + 2 * t / apex;
+  }
+  return apex === 1 ? 1 : 1 - 2 * (t - apex) / (1 - apex);
+}
+function plannedContourAt(shape, peakPosition, t) {
+  switch (shape) {
+    case "arch":
+      return tent(t, peakPosition);
+    case "ascending":
+      return -1 + 2 * t;
+    case "descending":
+      return 1 - 2 * t;
+    case "wave":
+      return t < 0.5 ? tent(2 * t, 0.5) : tent(2 * t - 1, 0.5);
+    case "static":
+      return 0;
+  }
 }
-function ornamentedVelocity(style, note2) {
-  if (note2.velocity === void 0 && style !== "ghost" && style !== "accent") {
-    return void 0;
+
+// src/generate/plan/validate.ts
+var MASS_TOLERANCE = 1e-9;
+function assertString(value, name) {
+  if (typeof value !== "string") {
+    throw new InvalidInputError(`${name} must be a string; received ${describeRejected(value)}`);
   }
-  const velocity = note2.velocity ?? DEFAULT_VELOCITY2;
-  if (style === "ghost") {
-    return clampVelocity(velocity * GHOST_VELOCITY_SCALE);
+  return value;
+}
+function assertSpanOrder(startBeat, endBeat, name) {
+  if (endBeat < startBeat) {
+    throw new InvalidInputError(
+      `${name}.endBeat must be at least ${name}.startBeat; received ${endBeat} < ${startBeat}`
+    );
   }
-  if (style === "accent") {
-    return clampVelocity(velocity + ACCENT_VELOCITY_BOOST);
+}
+function assertNullable(value, name, validate) {
+  if (value === void 0) {
+    throw new InvalidInputError(`${name} must be present; received undefined`);
   }
-  return velocity;
+  return value === null ? null : validate(value, name);
 }
-function clampVelocity(velocity) {
-  return Math.min(MAX_VELOCITY2, Math.max(MIN_VELOCITY2, Math.round(velocity)));
+function assertMassDistribution(value, length, name) {
+  const shares = assertArray(value, name);
+  if (shares.length !== length) {
+    throw new InvalidInputError(`${name} must have length ${length}; received ${shares.length}`);
+  }
+  let sum = 0;
+  for (let index = 0; index < shares.length; index += 1) {
+    const share = assertFiniteNumber(shares[index], `${name}[${index}]`);
+    if (share < 0) {
+      throw new InvalidInputError(`${name}[${index}] must be at least 0; received ${share}`);
+    }
+    sum += share;
+  }
+  if (Math.abs(sum - 1) > MASS_TOLERANCE) {
+    throw new InvalidInputError(`${name} must sum to 1; received ${sum}`);
+  }
+  return shares;
 }
-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);
-  if (asked.amount !== void 0) {
-    assertRange(asked.amount, 0, 1, "ornament amount");
+function assertResolvedKeyField(value, name) {
+  const read = assertRecord(value, name);
+  try {
+    resolveKey(read);
+  } catch (error) {
+    if (error instanceof InvalidInputError) {
+      throw new InvalidInputError(`${name} must be a valid key: ${error.message}`);
+    }
+    throw error;
   }
-  const ctx = resolveContextWith(asked.ctx, { ornament: asked.amount });
-  const amount = ctx.ornament ?? DEFAULT_AMOUNT;
-  const draw = ctx.part("ornament");
-  const sounding2 = dropSilentNotes(notes);
-  const ordered = [...sounding2].sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
-  const previousOf = previousOnsets(ordered);
-  const nextOf = nextOnsets(ordered);
-  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)) {
-      return decorated;
+  return read;
+}
+function assertPlannedSection(value, name) {
+  const read = assertRecord(value, name);
+  assertString(read.label, `${name}.label`);
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  return read;
+}
+function assertPlannedPhrase(value, name, sectionCount, motifCount) {
+  const read = assertRecord(value, name);
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  assertNullable(
+    read.section,
+    `${name}.section`,
+    (v, n) => assertInteger(v, n, 0, Math.max(sectionCount - 1, 0))
+  );
+  assertNullable(read.cadence, `${name}.cadence`, (v, n) => assertOneOf(v, CADENCE_TYPES, n));
+  assertOneOf(read.shape, MELODIC_CONTOUR_SHAPES, `${name}.shape`);
+  assertRange(read.peakPosition, 0, 1, `${name}.peakPosition`);
+  const register = assertRecord(
+    read.register,
+    `${name}.register`
+  );
+  assertMidiPitch(register.low, `${name}.register.low`);
+  assertMidiPitch(register.high, `${name}.register.high`);
+  assertRange(register.mean, 0, 127, `${name}.register.mean`);
+  assertRange(read.onsetDensity, 0, Number.MAX_SAFE_INTEGER, `${name}.onsetDensity`);
+  const motifs = assertArray(read.motifs, `${name}.motifs`);
+  for (let index = 0; index < motifs.length; index += 1) {
+    assertInteger(
+      motifs[index],
+      `${name}.motifs[${index}]`,
+      0,
+      Math.max(motifCount - 1, 0)
+    );
+  }
+  return read;
+}
+function assertPlannedChord(value, name, keys) {
+  const read = assertRecord(value, name);
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  const keyIndex = assertInteger(read.key, `${name}.key`, 0, Math.max(keys.length - 1, 0));
+  const roman = assertString(read.roman, `${name}.roman`);
+  try {
+    romanToChord(roman, keys[keyIndex]);
+  } catch (error) {
+    if (error instanceof InvalidInputError) {
+      throw new InvalidInputError(
+        `${name}.roman must be readable by romanToChord; received ${describeRejected(roman)}: ${error.message}`
+      );
     }
-    if (!sustainsStrokes(gaps.get(note2) ?? Number.POSITIVE_INFINITY, ctx.bpm, ctx.difficulty)) {
-      return decorated;
+    throw error;
+  }
+  return read;
+}
+function assertPlannedMotifRelation(value, name) {
+  const read = assertRecord(value, name);
+  assertOneOf(read.kind, MOTIF_RELATION_KINDS, `${name}.kind`);
+  assertFlag(read.sequence, `${name}.sequence`);
+  assertFiniteNumber(read.semitones, `${name}.semitones`);
+  if (read.kind === "tonalTransposition") {
+    assertFiniteNumber(read.degrees, `${name}.degrees`);
+  } else if (read.degrees !== void 0) {
+    assertFiniteNumber(read.degrees, `${name}.degrees`);
+  }
+  const timeRatio = assertFiniteNumber(read.timeRatio, `${name}.timeRatio`);
+  if (timeRatio <= 0) {
+    throw new InvalidInputError(`${name}.timeRatio must be positive; received ${timeRatio}`);
+  }
+  return read;
+}
+function assertPlannedMotif(value, name, ownIndex, motifCount, phraseCount) {
+  const read = assertRecord(value, name);
+  assertInteger(read.phrase, `${name}.phrase`, 0, Math.max(phraseCount - 1, 0));
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  assertPositiveInt(read.notes, `${name}.notes`);
+  const from = assertNullable(
+    read.from,
+    `${name}.from`,
+    (v, n) => assertInteger(v, n, 0, Math.max(motifCount - 1, 0))
+  );
+  if (from !== null && from >= ownIndex) {
+    throw new InvalidInputError(
+      `${name}.from must be less than this motif's own index (${ownIndex}); received ${from}`
+    );
+  }
+  const relation = assertNullable(read.relation, `${name}.relation`, assertPlannedMotifRelation);
+  if (from === null && relation !== null) {
+    throw new InvalidInputError(
+      `${name}.relation must be null for a root motif (from = null); received a relation`
+    );
+  }
+  const rhythm = assertNullable(read.rhythm, `${name}.rhythm`, (v, n) => assertArray(v, n));
+  if (rhythm !== null) {
+    if (from !== null) {
+      throw new InvalidInputError(`${name}.rhythm must be null for a derived statement`);
     }
-    if (!draw.prob(amount, style, note2.startBeat, note2.pitch)) {
-      return decorated;
+    if (rhythm.length !== read.notes - 1) {
+      throw new InvalidInputError(
+        `${name}.rhythm must hold notes - 1 (${read.notes - 1}) gaps; received ${rhythm.length}`
+      );
     }
-    decorated.articulation = articulationOf(style);
-    const velocity = ornamentedVelocity(style, note2);
-    if (velocity !== void 0) {
-      decorated.velocity = velocity;
+    let total = 0;
+    for (let index = 0; index < rhythm.length; index += 1) {
+      const gap = assertFiniteNumber(rhythm[index], `${name}.rhythm[${index}]`);
+      if (gap <= 0) {
+        throw new InvalidInputError(`${name}.rhythm[${index}] must be positive; received ${gap}`);
+      }
+      total += gap;
     }
-    return decorated;
-  });
-}
-function previousOnsets(ordered) {
-  const previousOf = /* @__PURE__ */ new Map();
-  let earlier;
-  for (const note2 of ordered) {
-    if (earlier !== void 0 && earlier.startBeat === note2.startBeat) {
-      previousOf.set(note2, previousOf.get(earlier));
-    } else {
-      previousOf.set(note2, earlier);
+    if (total >= endBeat - startBeat - BEAT_EPS) {
+      throw new InvalidInputError(
+        `${name}.rhythm must sum to less than the statement's length (${endBeat - startBeat}); received ${total}`
+      );
     }
-    earlier = note2;
   }
-  return previousOf;
+  return read;
 }
-function nextOnsets(ordered) {
-  const nextOf = /* @__PURE__ */ new Map();
-  let later;
-  for (let index = ordered.length - 1; index >= 0; index -= 1) {
-    const note2 = ordered[index];
-    if (!note2) continue;
-    if (later !== void 0 && later.startBeat === note2.startBeat) {
-      nextOf.set(note2, nextOf.get(later));
-    } else {
-      nextOf.set(note2, later);
-    }
-    later = note2;
-  }
-  return nextOf;
+function assertPlannedRhythm(value, name) {
+  const read = assertRecord(value, name);
+  assertMassDistribution(read.onsetLevels, 6, `${name}.onsetLevels`);
+  assertMassDistribution(read.interOnsetShares, RHYTHM_IOI_BINS.length, `${name}.interOnsetShares`);
+  assertRange(read.syncopation, 0, 1, `${name}.syncopation`);
+  return read;
 }
-function strokeGaps(ordered) {
-  const distinct = [...new Set(ordered.map((note2) => note2.startBeat))].sort((a, b) => a - b);
-  const gapAt = /* @__PURE__ */ new Map();
-  for (let index = 0; index < distinct.length; index += 1) {
-    const beat = distinct[index] ?? 0;
-    const before = index === 0 ? Number.POSITIVE_INFINITY : beat - (distinct[index - 1] ?? 0);
-    const after = index === distinct.length - 1 ? Number.POSITIVE_INFINITY : (distinct[index + 1] ?? 0) - beat;
-    gapAt.set(beat, Math.min(before, after));
+function assertCompositionPlan(value, name = "composition plan") {
+  const read = assertRecord(value, name);
+  if (read.planVersion !== COMPOSITION_PLAN_VERSION) {
+    throw new InvalidInputError(
+      `${name}.planVersion must be ${COMPOSITION_PLAN_VERSION}; received ${describeRejected(read.planVersion)}`
+    );
   }
-  const gaps = /* @__PURE__ */ new Map();
-  for (const note2 of ordered) {
-    gaps.set(note2, gapAt.get(note2.startBeat) ?? Number.POSITIVE_INFINITY);
+  assertInteger(read.seed, `${name}.seed`, 0, 4294967295);
+  assertInteger(
+    read.algorithmVersion,
+    `${name}.algorithmVersion`,
+    MIN_ALGORITHM_VERSION,
+    ALGORITHM_VERSION
+  );
+  const keys = assertArray(read.keys, `${name}.keys`);
+  if (keys.length === 0) {
+    throw new InvalidInputError(`${name}.keys must hold at least one key; received an empty array`);
   }
-  return gaps;
+  for (let index = 0; index < keys.length; index += 1) {
+    assertResolvedKeyField(keys[index], `${name}.keys[${index}]`);
+  }
+  assertMeterMap(read.meters, `${name}.meters`);
+  const span = assertRecord(
+    read.span,
+    `${name}.span`
+  );
+  const spanStart = assertFiniteNumber(span.startBeat, `${name}.span.startBeat`);
+  const spanEnd = assertFiniteNumber(span.endBeat, `${name}.span.endBeat`);
+  assertSpanOrder(spanStart, spanEnd, `${name}.span`);
+  assertRange(span.bars, 0, Number.MAX_SAFE_INTEGER, `${name}.span.bars`);
+  const sections = assertArray(read.sections, `${name}.sections`);
+  for (let index = 0; index < sections.length; index += 1) {
+    assertPlannedSection(sections[index], `${name}.sections[${index}]`);
+  }
+  const phrases = assertArray(read.phrases, `${name}.phrases`);
+  const motifs = assertArray(read.motifs, `${name}.motifs`);
+  for (let index = 0; index < phrases.length; index += 1) {
+    assertPlannedPhrase(
+      phrases[index],
+      `${name}.phrases[${index}]`,
+      sections.length,
+      motifs.length
+    );
+  }
+  const harmony = assertArray(read.harmony, `${name}.harmony`);
+  for (let index = 0; index < harmony.length; index += 1) {
+    assertPlannedChord(harmony[index], `${name}.harmony[${index}]`, keys);
+  }
+  for (let index = 0; index < motifs.length; index += 1) {
+    assertPlannedMotif(
+      motifs[index],
+      `${name}.motifs[${index}]`,
+      index,
+      motifs.length,
+      phrases.length
+    );
+  }
+  assertPlannedRhythm(read.rhythm, `${name}.rhythm`);
+  return read;
 }
 
-// src/generate/progression/index.ts
-var DEFAULT_TS6 = { numerator: 4, denominator: 4 };
-var PROG_STYLES = Object.freeze(["minimal", "dance", "idol", "rock"]);
-var BORROWED_DEGREES = Object.freeze({
-  /** Flat submediant: bVI. */
-  bVI: 8,
-  /** Flat subtonic: bVII. */
-  bVII: 10,
-  /** Flat mediant: bIII. */
-  bIII: 11,
-  /** Minor subdominant borrowed from the parallel minor: iv. */
-  iv: 12,
-  /** Neapolitan: bII. */
-  bII: 13,
-  /** Sharp subdominant, the diminished #IV. */
-  sharpIV: 14
-});
+// src/generate/plan/timeline.ts
+function planTimeline(plan) {
+  return planChordTimeline(assertCompositionPlan(plan));
+}
+function planChordTimeline(plan) {
+  const spans = plan.harmony.map((chord) => {
+    const key = plan.keys[chord.key];
+    return spanFromChord(romanToChord(chord.roman, key), chord.startBeat);
+  });
+  return chordTimelineFromChords(spans, plan.span.endBeat);
+}
+
+// src/generate/plan/harmony.ts
+var HARMONY_OK_KIND_NAMES = [
+  "chordTone",
+  "tension",
+  "suspension",
+  "appoggiatura",
+  "anticipation",
+  "passing",
+  "neighbor"
+];
+var HARMONY_OK_KINDS = new Set(HARMONY_OK_KIND_NAMES);
+var CADENCE_DEGREES = {
+  authentic: [1, 3],
+  plagal: [1, 3],
+  half: [2, 5, 7],
+  phrygian: [2, 5, 7],
+  modal: [1]
+};
+function planKeyAt(plan) {
+  const regions = [...plan.harmony].sort((a, b) => a.startBeat - b.startBeat).map((chord) => ({
+    startBeat: chord.startBeat,
+    endBeat: chord.endBeat,
+    key: plan.keys[chord.key],
+    confidence: 1
+  }));
+  return keyLookup(regions, plan.keys[0]);
+}
+function cadencePitchClasses(plan, timeline, cadence, beat) {
+  if (cadence === "deceptive") {
+    const chord = timeline.at(beat);
+    return chord === null ? null : chordPitchClasses(chord);
+  }
+  const entry = plan.harmony.find((chord) => beat >= chord.startBeat && beat < chord.endBeat);
+  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);
+  const scaleAt2 = (beat) => scaleOf(keyAt(beat));
+  return (line) => {
+    const analyzed = analyzeVoice(line, timeline.at, scaleAt2);
+    return line.map((note2, index) => {
+      const position = positionClass(note2.startBeat, plan.meters);
+      if (position === "off") {
+        return null;
+      }
+      const kinds = (analyzed[index]?.labels ?? []).map((label) => label.kind);
+      if (kinds.some((kind) => HARMONY_OK_KINDS.has(kind))) {
+        return null;
+      }
+      const lenient = position === "weak" || timeline.at(note2.startBeat) === null;
+      return lenient && isScaleTone(note2.pitch, scaleAt2(note2.startBeat)) ? null : kinds;
+    });
+  };
+}
+
+// src/generate/melody/pitch-dp.ts
+var NO_LEAP = 0;
+var LEAP_UP = 1;
+var LEAP_DOWN = 2;
+var LEAP_STATES = 3;
+var SEARCH_LABEL = "melody pitch search";
+var WIDEST_THIRD = 4;
+var LEAP_CONTINUATION_COST = 0.5;
+function intervalCost(size) {
+  if (size === 0) {
+    return 0.2;
+  }
+  if (size <= 2) {
+    return 0;
+  }
+  if (size <= WIDEST_THIRD) {
+    return 0.3;
+  }
+  if (size <= 7) {
+    return 0.6;
+  }
+  return 1;
+}
+function leapOf(delta) {
+  if (Math.abs(delta) <= WIDEST_THIRD) {
+    return NO_LEAP;
+  }
+  return delta > 0 ? LEAP_UP : LEAP_DOWN;
+}
+function stepCost(from, to, leap, bothFixed) {
+  const delta = to - from;
+  const size = Math.abs(delta);
+  if (!bothFixed && isForbiddenMelodicLeap(from, to)) {
+    return Number.POSITIVE_INFINITY;
+  }
+  let cost = intervalCost(size);
+  if (leap === LEAP_UP && delta > 0 || leap === LEAP_DOWN && delta < 0) {
+    cost += LEAP_CONTINUATION_COST;
+  }
+  return cost;
+}
+function searchPitches(slots, budget, extra) {
+  const first = slots[0];
+  if (first === void 0) {
+    return [];
+  }
+  let previous = allocateCandidateTable(
+    first.candidates.length,
+    LEAP_STATES,
+    SEARCH_LABEL,
+    budget
+  ).fill(Number.POSITIVE_INFINITY);
+  for (let j = 0; j < first.candidates.length; j += 1) {
+    previous[j * LEAP_STATES + NO_LEAP] = first.cost(first.candidates[j]);
+  }
+  const backs = [];
+  for (let k = 1; k < slots.length; k += 1) {
+    const before = slots[k - 1];
+    const slot = slots[k];
+    const unary = slot.candidates.map((pitch) => slot.cost(pitch));
+    const current = allocateCandidateTable(
+      slot.candidates.length,
+      LEAP_STATES,
+      SEARCH_LABEL,
+      budget
+    ).fill(Number.POSITIVE_INFINITY);
+    const back = allocateChoiceTable(
+      slot.candidates.length,
+      LEAP_STATES,
+      SEARCH_LABEL,
+      budget
+    ).fill(-1);
+    const bothFixed = before.fixed && slot.fixed;
+    for (let state2 = 0; state2 < previous.length; state2 += 1) {
+      const reached = previous[state2];
+      if (reached === Number.POSITIVE_INFINITY) {
+        continue;
+      }
+      const from = before.candidates[Math.floor(state2 / LEAP_STATES)];
+      const leap = state2 % LEAP_STATES;
+      for (let j = 0; j < slot.candidates.length; j += 1) {
+        const to = slot.candidates[j];
+        const step = stepCost(from, to, leap, bothFixed);
+        if (step === Number.POSITIVE_INFINITY) {
+          continue;
+        }
+        const total = reached + step + unary[j] + (extra ? extra(k, from, to) : 0);
+        const index = j * LEAP_STATES + leapOf(to - from);
+        if (total < current[index]) {
+          current[index] = total;
+          back[index] = state2;
+        }
+      }
+    }
+    backs.push(back);
+    previous = current;
+  }
+  let best = -1;
+  for (let state2 = 0; state2 < previous.length; state2 += 1) {
+    if (previous[state2] < Number.POSITIVE_INFINITY && (best < 0 || previous[state2] < previous[best])) {
+      best = state2;
+    }
+  }
+  if (best < 0) {
+    return null;
+  }
+  const pitches = new Array(slots.length);
+  let state = best;
+  for (let k = slots.length - 1; k >= 0; k -= 1) {
+    pitches[k] = slots[k].candidates[Math.floor(state / LEAP_STATES)];
+    if (k > 0) {
+      state = backs[k - 1][state];
+    }
+  }
+  return pitches;
+}
+
+// src/generate/melody/derive.ts
+var VARIATION_STEP_COST = 0.2;
+var OCTAVE = 12;
+var LEVEL_TARGET_COST = 0.1;
+var LEVEL_PLAN_COST = 0.02;
+var LEVEL_REACH = 24;
+var TONAL_LEVEL_REACH = 14;
+function stretched(cell, timeRatio) {
+  return timeRatio === 1 ? cell : transformMotif(cell, "augment", timeRatio);
+}
+function shaped(cell, relation) {
+  switch (relation.kind) {
+    case "repetition":
+      return cell;
+    case "transposition":
+    case "tonalTransposition":
+      return stretched(cell, relation.timeRatio);
+    case "inversion":
+      return stretched(transformMotif(cell, "invert"), relation.timeRatio);
+    case "retrograde":
+      return stretched(transformMotif(cell, "retrograde"), relation.timeRatio);
+    case "retrogradeInversion":
+      return stretched(
+        transformMotif(transformMotif(cell, "invert"), "retrograde"),
+        relation.timeRatio
+      );
+    case "augmentation":
+      return transformMotif(cell, "augment", relation.timeRatio);
+    case "diminution":
+      return transformMotif(cell, "diminish", 1 / relation.timeRatio);
+  }
+}
+function relationLevels(kind, low = -LEVEL_REACH, high = LEVEL_REACH) {
+  const between = (from, to, skipZero) => {
+    const levels = [];
+    for (let level = Math.ceil(from); level <= to; level += 1) {
+      if (!(skipZero && level === 0)) levels.push(level);
+    }
+    return levels;
+  };
+  switch (kind) {
+    case "repetition":
+    case "augmentation":
+    case "diminution":
+      return [-OCTAVE, 0, OCTAVE];
+    case "transposition":
+      return between(low, high, true);
+    case "tonalTransposition":
+      return between(-TONAL_LEVEL_REACH, TONAL_LEVEL_REACH, true);
+    case "inversion":
+    case "retrograde":
+    case "retrogradeInversion":
+      return between(low, high, false);
+  }
+}
+function replayAt(source, relation, level, startBeat, key) {
+  const head = source[0];
+  const cell = shaped({ notes: source.map((n) => ({ ...n })) }, relation);
+  const first = cell.notes[0];
+  const offset = startBeat - first.startBeat;
+  const shift = head.pitch + level - first.pitch;
+  return cell.notes.map((n) => ({
+    ...n,
+    pitch: relation.kind === "tonalTransposition" ? shiftByScaleDegrees(n.pitch, level, key) : n.pitch + shift,
+    startBeat: n.startBeat + offset
+  }));
+}
+function clipStatement(notes, endBeat) {
+  return notes.filter((n) => n.startBeat < endBeat - BEAT_EPS).map((n) => ({ ...n, durationBeat: Math.min(n.durationBeat, endBeat - n.startBeat) }));
+}
+function outsideCount(notes, frame) {
+  return notes.filter((n) => n.pitch < frame.low || n.pitch > frame.high).length;
+}
+function nearerLevel(level, best, planned) {
+  const distance = Math.abs(level - planned);
+  const bestDistance = Math.abs(best - planned);
+  return distance < bestDistance || distance === bestDistance && level < best;
+}
+function repairStatement(notes, forced, frame) {
+  const slots = notes.map(
+    (n, index) => forced[index] ? {
+      candidates: frame.candidatesAt(n.startBeat),
+      cost: frame.costAt(n.startBeat),
+      fixed: false
+    } : { candidates: [n.pitch], cost: () => 0, fixed: true }
+  );
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(
+      `no repair fits the statement into the register ${frame.low}..${frame.high}`,
+      { at: frame.at }
+    );
+  }
+  return notes.map((n, index) => ({ ...n, pitch: pitches[index] }));
+}
+function placeDerived(source, relation, startBeat, endBeat, key, frame, before) {
+  const planned = relation.kind === "tonalTransposition" ? relation.degrees ?? 0 : relation.semitones;
+  const replay = (level) => clipStatement(replayAt(source, relation, level, startBeat, key), endBeat);
+  const base = replay(0).map((n) => n.pitch);
+  const levels = relationLevels(
+    relation.kind,
+    Math.max(-LEVEL_REACH, frame.low - Math.min(...base)),
+    Math.min(LEVEL_REACH, frame.high - Math.max(...base))
+  );
+  let best = null;
+  for (const level of levels) {
+    const notes2 = replay(level);
+    if (outsideCount(notes2, frame) > 0) {
+      continue;
+    }
+    const distance = notes2.reduce((sum, n) => sum + Math.abs(n.pitch - frame.targetAt(n.startBeat)), 0) / notes2.length;
+    const cost = frame.misfits(notes2, before) + LEVEL_TARGET_COST * distance + LEVEL_PLAN_COST * Math.abs(level - planned);
+    if (best === null || cost < best.cost || cost === best.cost && nearerLevel(level, best.level, planned)) {
+      best = { level, notes: notes2, cost };
+    }
+  }
+  if (best !== null) {
+    return best.notes;
+  }
+  let fallback = null;
+  for (const level of relationLevels(relation.kind)) {
+    const notes2 = replay(level);
+    const outside = outsideCount(notes2, frame);
+    if (fallback === null || outside < fallback.outside || outside === fallback.outside && nearerLevel(level, fallback.level, planned)) {
+      fallback = { level, notes: notes2, outside };
+    }
+  }
+  const notes = fallback.notes;
+  return repairStatement(
+    notes,
+    notes.map((n) => n.pitch < frame.low || n.pitch > frame.high),
+    frame
+  );
+}
+function varyStatement(source, startBeat, frame) {
+  const offset = startBeat - source[0].startBeat;
+  const last = source.length - 1;
+  const inside = (pitch) => pitch >= frame.low && pitch <= frame.high;
+  const outer = [source[0].pitch, source[last].pitch];
+  const shift = [0, OCTAVE, -OCTAVE].find((s) => outer.every((pitch) => inside(pitch + s)));
+  const notes = source.map((n) => ({ ...n, startBeat: n.startBeat + offset }));
+  const slots = notes.map(
+    (n, index) => (index === 0 || index === last) && shift !== void 0 ? { candidates: [n.pitch + shift], cost: () => 0, fixed: true } : {
+      candidates: frame.candidatesAt(n.startBeat),
+      cost: frame.costAt(n.startBeat),
+      fixed: false
+    }
+  );
+  const pitches = searchPitches(
+    slots,
+    frame.budget,
+    (index, from, to) => VARIATION_STEP_COST * Math.abs(
+      to - from - (source[index].pitch - source[index - 1].pitch)
+    )
+  );
+  if (pitches === null) {
+    throw new NoSolutionError(`no variation line fits the register ${frame.low}..${frame.high}`, {
+      at: frame.at
+    });
+  }
+  return notes.map((n, index) => ({ ...n, pitch: pitches[index] }));
+}
+
+// src/generate/melody/index.ts
+var RHYTHM_SUBDIVISION = 4;
+var OFF_SCALE_COST = 1;
+var TARGET_COST = 0.1;
+var TIE_BREAK = 1e-6;
+var SEARCH_STATES_SQUARED = 9;
+function melodyContext(plan, input) {
+  const fromPlan = { seed: plan.seed, algorithmVersion: plan.algorithmVersion };
+  if (input === void 0) {
+    return resolveContext(fromPlan);
+  }
+  if (typeof input === "number") {
+    return resolveContext({ ...fromPlan, seed: input });
+  }
+  const read = assertRecord(input, "ctx");
+  if (read.rng !== void 0) {
+    throw new InvalidInputError(
+      "ctx.rng cannot drive a melody: every onset and tie-break is drawn at an address of phrase and beat under a seed; pass a seed instead"
+    );
+  }
+  return resolveContext({
+    ...read,
+    seed: read.seed ?? plan.seed,
+    algorithmVersion: read.algorithmVersion ?? plan.algorithmVersion
+  });
+}
+function chordEntryAt(plan, beat) {
+  return plan.harmony.find((chord) => beat >= chord.startBeat && beat < chord.endBeat);
+}
+function scaleAt(scene, beat) {
+  return scene.scales[chordEntryAt(scene.plan, beat)?.key ?? 0];
+}
+function targetPitch(phrase, beat) {
+  const length = phrase.endBeat - phrase.startBeat;
+  const t = length > 0 ? Math.min(Math.max((beat - phrase.startBeat) / length, 0), 1) : 0;
+  const { low, high, mean } = phrase.register;
+  return mean + (high - low) / 2 * plannedContourAt(phrase.shape, phrase.peakPosition, t);
+}
+function registerPitches(phrase) {
+  const pitches = [];
+  for (let pitch = phrase.register.low; pitch <= phrase.register.high; pitch += 1) {
+    pitches.push(pitch);
+  }
+  return pitches;
+}
+function frameOf(scene, index) {
+  const phrase = scene.plan.phrases[index];
+  const { low, high } = phrase.register;
+  const register = registerPitches(phrase);
+  const draw = scene.ctx.part("melody");
+  return {
+    low,
+    high,
+    at: phrase.startBeat,
+    budget: scene.budget,
+    candidatesAt: (beat) => {
+      const position = positionClass(beat, scene.plan.meters);
+      const chord = scene.timeline.at(beat);
+      const tones = position === "strong" && chord !== null ? chordPitchClasses(chord) : null;
+      const scale = scaleAt(scene, beat);
+      const candidates = position === "off" ? register : tones !== null ? register.filter((pitch) => tones.includes(pitchClassOf(pitch))) : register.filter((pitch) => isScaleTone(pitch, scale));
+      if (candidates.length === 0) {
+        throw new NoSolutionError(
+          `no ${position} pitch at beat ${beat} fits the register ${low}..${high}`,
+          { at: phrase.startBeat }
+        );
+      }
+      return candidates;
+    },
+    costAt: (beat) => {
+      const off = positionClass(beat, scene.plan.meters) === "off";
+      const scale = scaleAt(scene, beat);
+      const target = targetPitch(phrase, beat);
+      return (pitch) => {
+        let cost = TARGET_COST * Math.abs(pitch - target);
+        if (off && !isScaleTone(pitch, scale)) {
+          cost += OFF_SCALE_COST;
+        }
+        return cost + draw.float(0, TIE_BREAK, index, "tie", beat, pitch);
+      };
+    },
+    targetAt: (beat) => targetPitch(phrase, beat),
+    misfits: (notes, before) => scene.harmonyMisfits([...before, ...notes]).slice(before.length).filter((kinds) => kinds !== null).length
+  };
+}
+function membersOf(plan) {
+  return plan.phrases.map((phrase, index) => {
+    const found = new Set(phrase.motifs);
+    plan.motifs.forEach((motif, m) => {
+      if (motif.phrase === index) {
+        found.add(m);
+      }
+    });
+    return [...found].sort(
+      (a, b) => (plan.motifs[a]?.startBeat ?? 0) - (plan.motifs[b]?.startBeat ?? 0) || a - b
+    );
+  });
+}
+function segmentsOf(scene, index) {
+  const phrase = scene.plan.phrases[index];
+  const segments = [];
+  let cursor = phrase.startBeat;
+  for (const m of scene.members[index]) {
+    const motif = scene.plan.motifs[m];
+    if (motif === void 0) {
+      continue;
+    }
+    if (motif.startBeat > cursor + BEAT_EPS) {
+      segments.push({ startBeat: cursor, endBeat: motif.startBeat, motif: null });
+    }
+    segments.push({ startBeat: motif.startBeat, endBeat: motif.endBeat, motif: m });
+    cursor = Math.max(cursor, motif.endBeat);
+  }
+  if (phrase.endBeat > cursor + BEAT_EPS) {
+    segments.push({ startBeat: cursor, endBeat: phrase.endBeat, motif: null });
+  }
+  return segments;
+}
+function notesAt(onsets, endBeat) {
+  return onsets.map((startBeat, i) => ({
+    pitch: 0,
+    startBeat,
+    durationBeat: (onsets[i + 1] ?? endBeat) - startBeat
+  }));
+}
+function onsetSlots(scene, startBeat, endBeat) {
+  const { meters } = scene.plan;
+  const slots = [startBeat];
+  let bar2 = barStartBeat(startBeat, meters);
+  while (bar2 < endBeat - BEAT_EPS) {
+    const barEnd = bar2 + beatsPerBarAt(bar2, meters);
+    for (let k = 0; bar2 + k / RHYTHM_SUBDIVISION < barEnd - BEAT_EPS; k += 1) {
+      const beat = bar2 + k / RHYTHM_SUBDIVISION;
+      if (beat > startBeat + BEAT_EPS && beat < endBeat - BEAT_EPS) {
+        slots.push(beat);
+      }
+    }
+    assertGenerationBudget(slots.length, "melody onset slots", scene.budget);
+    bar2 = barEnd;
+  }
+  return slots;
+}
+function drawOnsets(scene, phraseIndex, startBeat, endBeat, count) {
+  const slots = onsetSlots(scene, startBeat, endBeat);
+  assertGenerationBudget(slots.length * Math.max(1, count - 1), "melody onset slots", scene.budget);
+  if (count - 1 > slots.length - 1) {
+    throw new NoSolutionError(
+      `${count} onsets do not fit the sixteenth grid of beats ${startBeat}..${endBeat}`,
+      { at: scene.plan.phrases[phraseIndex].startBeat }
+    );
+  }
+  const levels = slots.map((beat) => rhythmLevel(beat, scene.plan.meters));
+  const perLevel = /* @__PURE__ */ new Map();
+  for (const level of levels) {
+    perLevel.set(level, (perLevel.get(level) ?? 0) + 1);
+  }
+  const levelWeight = levels.map(
+    (level) => (scene.plan.rhythm.onsetLevels[level] ?? 0) / perLevel.get(level)
+  );
+  const draw = scene.ctx.part("melody");
+  const onsets = [startBeat];
+  let current = 0;
+  for (let k = 1; k < count; k += 1) {
+    const last = slots.length - 1 - (count - 1 - k);
+    const candidates = [];
+    for (let j = current + 1; j <= last; j += 1) candidates.push(j);
+    const gapShare = (j) => scene.plan.rhythm.interOnsetShares[ioiBinIndex(slots[j] - slots[current])] ?? 0;
+    let weights = candidates.map((j) => levelWeight[j] * gapShare(j));
+    if (!weights.some((w) => w > 0)) weights = candidates.map((j) => levelWeight[j]);
+    if (!weights.some((w) => w > 0)) weights = candidates.map(() => 1);
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    let target = draw.float(0, 1, phraseIndex, "onset", startBeat, k) * total;
+    let pick = candidates.length - 1;
+    for (let c = 0; c < candidates.length; c += 1) {
+      target -= weights[c];
+      if (target < 0) {
+        pick = c;
+        break;
+      }
+    }
+    current = candidates[pick];
+    onsets.push(slots[current]);
+  }
+  return notesAt(onsets, endBeat);
+}
+function placeRhythm(scene, motif) {
+  const { rhythm, startBeat, endBeat, notes } = motif;
+  if (rhythm === null) {
+    return drawOnsets(scene, motif.phrase, startBeat, endBeat, notes);
+  }
+  const onsets = [startBeat];
+  for (const gap of rhythm) {
+    onsets.push(onsets.at(-1) + gap);
+  }
+  return notesAt(onsets, endBeat);
+}
+function searchedLine(rhythm, frame) {
+  const slots = rhythm.map((note2) => ({
+    candidates: frame.candidatesAt(note2.startBeat),
+    cost: frame.costAt(note2.startBeat),
+    fixed: false
+  }));
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(`no pitch line fits the register ${frame.low}..${frame.high}`, {
+      at: frame.at
+    });
+  }
+  return rhythm.map((note2, i) => ({ ...note2, pitch: pitches[i] }));
+}
+function statementOf(scene, m) {
+  const known = scene.statements.get(m);
+  if (known !== void 0) {
+    return known;
+  }
+  scene.inProgress.add(m);
+  const motif = scene.plan.motifs[m];
+  const frame = scene.frames[motif.phrase];
+  let notes;
+  if (motif.from === null) {
+    if (motif.endBeat - motif.startBeat <= BEAT_EPS) {
+      throw new NoSolutionError(`root motif ${m} spans no time to place its notes in`, {
+        at: frame.at
+      });
+    }
+    notes = searchedLine(placeRhythm(scene, motif), frame);
+  } else {
+    const source = statementOf(scene, motif.from);
+    notes = motif.relation === null ? varyStatement(source, motif.startBeat, frame) : placeDerived(
+      source,
+      motif.relation,
+      motif.startBeat,
+      motif.endBeat,
+      scaleAt(scene, motif.startBeat),
+      frame,
+      lineBefore(scene, motif.phrase, motif.startBeat)
+    );
+  }
+  scene.inProgress.delete(m);
+  scene.statements.set(m, notes);
+  return notes;
+}
+function freeNoteCount(scene, index, segment) {
+  const phrase = scene.plan.phrases[index];
+  const bars = barSpanOf(segment.startBeat, segment.endBeat, scene.plan.meters);
+  return Math.max(1, Math.round(phrase.onsetDensity * bars));
+}
+function freeSpan(scene, index, segment) {
+  const key = `${index}:${segment.startBeat}`;
+  const known = scene.free.get(key);
+  if (known !== void 0) {
+    return known;
+  }
+  const rhythm = drawOnsets(
+    scene,
+    index,
+    segment.startBeat,
+    segment.endBeat,
+    freeNoteCount(scene, index, segment)
+  );
+  const notes = searchedLine(rhythm, scene.frames[index]);
+  scene.free.set(key, notes);
+  return notes;
+}
+function lineBefore(scene, index, beat) {
+  const line = [];
+  for (const segment of segmentsOf(scene, index)) {
+    if (segment.endBeat > beat + BEAT_EPS) {
+      break;
+    }
+    if (segment.motif === null) {
+      line.push(...freeSpan(scene, index, segment));
+    } else if (!scene.inProgress.has(segment.motif)) {
+      line.push(...statementOf(scene, segment.motif));
+    }
+  }
+  return line.sort((a, b) => a.startBeat - b.startBeat);
+}
+function heldNoteIndex(scene, index, line, downbeat) {
+  const phrase = scene.plan.phrases[index];
+  const sounding2 = line.findIndex(
+    (note2) => note2.startBeat <= downbeat + BEAT_EPS && note2.startBeat + note2.durationBeat > downbeat + BEAT_EPS
+  );
+  return sounding2 >= 0 ? sounding2 : line.findIndex(
+    (note2) => note2.startBeat >= downbeat - BEAT_EPS && note2.startBeat < phrase.endBeat - BEAT_EPS
+  );
+}
+function repairCadence(scene, index, line, held) {
+  const phrase = scene.plan.phrases[index];
+  if (phrase.cadence === null) {
+    return;
+  }
+  let target = held;
+  for (let i = line.length - 1; target < 0 && i >= 0; i -= 1) {
+    if (positionClass(line[i].startBeat, scene.plan.meters) !== "off") {
+      target = i;
+    }
+  }
+  if (target < 0) {
+    return;
+  }
+  const note2 = line[target];
+  const allowed = cadencePitchClasses(scene.plan, scene.timeline, phrase.cadence, note2.startBeat);
+  if (allowed === null) {
+    return;
+  }
+  const frame = scene.frames[index];
+  const candidates = registerPitches(phrase).filter(
+    (pitch) => allowed.includes(pitchClassOf(pitch))
+  );
+  if (candidates.length === 0) {
+    throw new NoSolutionError(
+      `no pitch in the register ${frame.low}..${frame.high} can end the ${phrase.cadence} cadence`,
+      { at: frame.at }
+    );
+  }
+  if (allowed.includes(pitchClassOf(note2.pitch))) {
+    return;
+  }
+  const slots = line.map(
+    (n, i) => i === target ? { candidates, cost: frame.costAt(n.startBeat), fixed: false } : { candidates: [n.pitch], cost: () => 0, fixed: true }
+  );
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(`no cadence pitch joins its neighbours without an augmented step`, {
+      at: frame.at
+    });
+  }
+  note2.pitch = pitches[target];
+}
+function repickCutOnset(scene, index, line, held) {
+  const note2 = line[held];
+  const derived = scene.plan.motifs.some(
+    (motif) => motif.from !== null && note2.startBeat >= motif.startBeat - BEAT_EPS && note2.startBeat < motif.endBeat - BEAT_EPS
+  );
+  if (scene.plan.phrases[index].cadence !== null || derived) {
+    return;
+  }
+  const frame = scene.frames[index];
+  const candidates = frame.candidatesAt(note2.startBeat);
+  if (candidates.includes(note2.pitch)) {
+    return;
+  }
+  const slots = line.map(
+    (n, i) => i === held ? { candidates, cost: frame.costAt(n.startBeat), fixed: false } : { candidates: [n.pitch], cost: () => 0, fixed: true }
+  );
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(`no pitch at the final downbeat joins its neighbours`, {
+      at: frame.at
+    });
+  }
+  line[held] = { ...note2, pitch: pitches[held] };
+}
+function phraseLine(scene, index) {
+  const line = [];
+  for (const segment of segmentsOf(scene, index)) {
+    line.push(
+      ...segment.motif === null ? freeSpan(scene, index, segment) : statementOf(scene, segment.motif)
+    );
+  }
+  return line.sort((a, b) => a.startBeat - b.startBeat);
+}
+function chargePitchSearch(scene) {
+  const { plan } = scene;
+  let estimate = 0;
+  plan.phrases.forEach((phrase, index) => {
+    let searched = 0;
+    for (const segment of segmentsOf(scene, index)) {
+      const motif = segment.motif === null ? void 0 : plan.motifs[segment.motif];
+      if (motif === void 0) {
+        searched += freeNoteCount(scene, index, segment);
+      } else if (motif.relation === null) {
+        searched += motif.notes;
+      } else {
+        estimate += motif.notes * relationLevels(motif.relation.kind).length;
+      }
+    }
+    const register = Math.max(0, phrase.register.high - phrase.register.low + 1);
+    estimate += searched * SEARCH_STATES_SQUARED * register * register;
+  });
+  assertGenerationBudget(estimate, "melody pitch search", scene.budget);
+}
+function generateMelody(plan, opts) {
+  assertCompositionPlan(plan);
+  const asked = assertOptions(opts, "opts");
+  if (asked.budget !== void 0) {
+    assertPositiveInt(asked.budget, "budget", Number.MAX_SAFE_INTEGER);
+  }
+  const timeline = planChordTimeline(plan);
+  const scene = {
+    plan,
+    ctx: melodyContext(plan, asked.ctx),
+    budget: asked.budget,
+    timeline,
+    harmonyMisfits: planHarmonyMisfits(plan, timeline),
+    scales: plan.keys.map((key) => scaleOf(key)),
+    members: membersOf(plan),
+    frames: [],
+    statements: /* @__PURE__ */ new Map(),
+    free: /* @__PURE__ */ new Map(),
+    inProgress: /* @__PURE__ */ new Set()
+  };
+  scene.frames = plan.phrases.map((_, index) => frameOf(scene, index));
+  chargePitchSearch(scene);
+  const melody = [];
+  plan.phrases.forEach((_, index) => {
+    const line = phraseLine(scene, index);
+    const downbeat = finalDownbeat(plan.phrases[index], plan.meters);
+    let held = heldNoteIndex(scene, index, line, downbeat);
+    if (held >= 0) {
+      line.length = held + 1;
+      const note2 = line[held];
+      if (note2.startBeat < downbeat - BEAT_EPS) {
+        const cut = downbeat - note2.startBeat;
+        line[held] = { ...note2, durationBeat: cut };
+        line.push({ ...note2, startBeat: downbeat, durationBeat: note2.durationBeat - cut });
+        held += 1;
+        repickCutOnset(scene, index, line, held);
+      }
+    }
+    repairCadence(scene, index, line, held);
+    if (held >= 0) {
+      const note2 = line[held];
+      const phraseEnd = plan.phrases[index].endBeat;
+      line[held] = { ...note2, durationBeat: phraseEnd - note2.startBeat };
+    }
+    melody.push(...line);
+  });
+  melody.sort((a, b) => a.startBeat - b.startBeat);
+  return motifToNoteEvents({ notes: melody });
+}
+
+// src/generate/ornament/index.ts
+var ORNAMENT_STYLES = Object.freeze(["ghost", "flam", "drag", "slide", "accent"]);
+var DEFAULT_TS5 = { numerator: 4, denominator: 4 };
+var DEFAULT_STYLE2 = "ghost";
+var DEFAULT_AMOUNT = 0.5;
+var GHOST_VELOCITY_SCALE = 0.45;
+var ACCENT_VELOCITY_BOOST = 12;
+var DEFAULT_VELOCITY2 = 80;
+var MIN_VELOCITY2 = 1;
+var MAX_VELOCITY2 = 127;
+var SLIDE_MIN_SEMITONES = 1;
+function eligible(style, note2, previous, next, meter) {
+  const strong = isStrongBeat(note2.startBeat, meter);
+  switch (style) {
+    case "ghost":
+      return !strong;
+    case "flam":
+    case "accent":
+      return strong;
+    case "drag":
+      return !strong && next !== void 0 && isStrongBeat(next.startBeat, meter);
+    case "slide":
+      return previous !== void 0 && Math.abs(note2.pitch - previous.pitch) >= SLIDE_MIN_SEMITONES;
+  }
+}
+function articulationOf(style) {
+  return style;
+}
+function ornamentedVelocity(style, note2) {
+  if (note2.velocity === void 0 && style !== "ghost" && style !== "accent") {
+    return void 0;
+  }
+  const velocity = note2.velocity ?? DEFAULT_VELOCITY2;
+  if (style === "ghost") {
+    return clampVelocity(velocity * GHOST_VELOCITY_SCALE);
+  }
+  if (style === "accent") {
+    return clampVelocity(velocity + ACCENT_VELOCITY_BOOST);
+  }
+  return velocity;
+}
+function clampVelocity(velocity) {
+  return Math.min(MAX_VELOCITY2, Math.max(MIN_VELOCITY2, Math.round(velocity)));
+}
+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 meter = toMeterData(asked.ts ?? DEFAULT_TS5, "ts");
+  if (asked.amount !== void 0) {
+    assertRange(asked.amount, 0, 1, "ornament amount");
+  }
+  const ctx = resolveContextWith(asked.ctx, { ornament: asked.amount });
+  const amount = ctx.ornament ?? DEFAULT_AMOUNT;
+  const draw = ctx.part("ornament");
+  const sounding2 = dropSilentNotes(notes);
+  const ordered = [...sounding2].sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
+  const previousOf = previousOnsets(ordered);
+  const nextOf = nextOnsets(ordered);
+  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), meter)) {
+      return decorated;
+    }
+    if (!sustainsStrokes(gaps.get(note2) ?? Number.POSITIVE_INFINITY, ctx.bpm, ctx.difficulty)) {
+      return decorated;
+    }
+    if (!draw.prob(amount, style, note2.startBeat, note2.pitch)) {
+      return decorated;
+    }
+    decorated.articulation = articulationOf(style);
+    const velocity = ornamentedVelocity(style, note2);
+    if (velocity !== void 0) {
+      decorated.velocity = velocity;
+    }
+    return decorated;
+  });
+}
+function previousOnsets(ordered) {
+  const previousOf = /* @__PURE__ */ new Map();
+  let earlier;
+  for (const note2 of ordered) {
+    if (earlier !== void 0 && earlier.startBeat === note2.startBeat) {
+      previousOf.set(note2, previousOf.get(earlier));
+    } else {
+      previousOf.set(note2, earlier);
+    }
+    earlier = note2;
+  }
+  return previousOf;
+}
+function nextOnsets(ordered) {
+  const nextOf = /* @__PURE__ */ new Map();
+  let later;
+  for (let index = ordered.length - 1; index >= 0; index -= 1) {
+    const note2 = ordered[index];
+    if (!note2) continue;
+    if (later !== void 0 && later.startBeat === note2.startBeat) {
+      nextOf.set(note2, nextOf.get(later));
+    } else {
+      nextOf.set(note2, later);
+    }
+    later = note2;
+  }
+  return nextOf;
+}
+function strokeGaps(ordered) {
+  const distinct = [...new Set(ordered.map((note2) => note2.startBeat))].sort((a, b) => a - b);
+  const gapAt = /* @__PURE__ */ new Map();
+  for (let index = 0; index < distinct.length; index += 1) {
+    const beat = distinct[index] ?? 0;
+    const before = index === 0 ? Number.POSITIVE_INFINITY : beat - (distinct[index - 1] ?? 0);
+    const after = index === distinct.length - 1 ? Number.POSITIVE_INFINITY : (distinct[index + 1] ?? 0) - beat;
+    gapAt.set(beat, Math.min(before, after));
+  }
+  const gaps = /* @__PURE__ */ new Map();
+  for (const note2 of ordered) {
+    gaps.set(note2, gapAt.get(note2.startBeat) ?? Number.POSITIVE_INFINITY);
+  }
+  return gaps;
+}
+
+// src/generate/plan/derive.ts
+var PRESERVE_ASPECTS = [
+  "form",
+  "phraseLengths",
+  "harmonicFunction",
+  "harmonicRhythm",
+  "motifRelations",
+  "registerShape",
+  "rhythm"
+];
+var NEUTRAL_SHAPE = "arch";
+var NEUTRAL_PEAK_POSITION = 0.6;
+var SHAPE_KEEP_THRESHOLD = 0.5;
+var NEUTRAL_ONSET_LEVELS = Object.freeze([0, 1, 2, 3, 4, 5].map((level) => level / 15));
+var FUNCTION_DEGREES = {
+  tonic: [1, 6, 3],
+  subdominant: [4, 2],
+  dominant: [5, 7]
+};
+var STRONG_WEIGHT2 = 2;
+var HEPTATONIC_DEGREES = 7;
+function mod12(value) {
+  return (value % 12 + 12) % 12;
+}
+function lerp(weight, reference, neutral) {
+  return weight * reference + (1 - weight) * neutral;
+}
+function readPreserve(value) {
+  const read = value === void 0 ? {} : assertRecord(value, "opts.preserve");
+  const weights = {};
+  for (const aspect of PRESERVE_ASPECTS) {
+    const weight = read[aspect];
+    weights[aspect] = weight === void 0 ? 1 : assertRange(weight, 0, 1, `opts.preserve.${aspect}`);
+  }
+  return weights;
+}
+function readRegister(value) {
+  const read = assertRecord(value, "opts.register");
+  const low = assertMidiPitch(read.low, "opts.register.low");
+  const high = assertMidiPitch(read.high, "opts.register.high");
+  if (low > high) {
+    throw new InvalidInputError(
+      `opts.register.low must not exceed opts.register.high; received ${low} > ${high}`
+    );
+  }
+  return { low, high };
+}
+function rejectSuppliedRng(ctx) {
+  if (typeof ctx === "object" && ctx !== null && ctx.rng !== void 0) {
+    throw new InvalidInputError(
+      "opts.ctx.rng is not accepted: a composition plan records its seed, not a source"
+    );
+  }
+}
+function plannedKeys(profile, requested) {
+  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;
+  }
+  const target = resolveKey(requested);
+  if (target.variant !== home.variant || target.scale.modeMask12 !== home.scale.modeMask12) {
+    throw new InvalidInputError(
+      "opts.key must be in the same mode as the reference's home key; a key change moves the tonic only"
+    );
+  }
+  const step = spelledInterval(
+    { letter: home.tonic.letter, alter: home.tonic.alter },
+    { letter: target.tonic.letter, alter: target.tonic.alter }
+  );
+  const moved = regions.map(
+    (key) => ({
+      scale: {
+        rootPc: mod12(key.scale.rootPc + step.semitones),
+        modeMask12: key.scale.modeMask12
+      },
+      tonic: transposeByInterval({ letter: key.tonic.letter, alter: key.tonic.alter }, step),
+      variant: key.variant
+    })
+  );
+  moved[0] = target;
+  return moved;
+}
+function nearestBoundary(beat, boundaries) {
+  let best = beat;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const boundary of boundaries) {
+    const distance = Math.abs(boundary - beat);
+    if (distance < bestDistance - BEAT_EPS) {
+      best = boundary;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+function plannedSections(profile, weight, draw) {
+  const sections = profile.form.sections;
+  const boundaries = [profile.span.startBeat, profile.span.endBeat];
+  for (const phrase of profile.form.phrases) {
+    boundaries.push(phrase.startBeat, phrase.endBeat);
+  }
+  boundaries.sort((a, b) => a - b);
+  const planned = [];
+  sections.forEach((section, index) => {
+    const keep = sections.length < 2 || draw.prob(weight, "form", index);
+    const neighbour = index + 1 < sections.length ? index + 1 : index - 1;
+    const startBeat = nearestBoundary(section.startBeat, boundaries);
+    const endBeat = nearestBoundary(section.endBeat, boundaries);
+    if (endBeat - startBeat > BEAT_EPS) {
+      planned.push({
+        label: keep ? section.label : sections[neighbour]?.label ?? section.label,
+        startBeat,
+        endBeat
+      });
+    }
+  });
+  return planned;
+}
+function beatAfterBars(startBeat, bars, meters) {
+  let beat = startBeat;
+  let left = bars;
+  while (left > BEAT_EPS) {
+    const step = Math.min(1, left);
+    beat += step * beatsPerBarAt(beat, meters);
+    left -= step;
+  }
+  return beat;
+}
+function barsBetween(startBeat, endBeat, meters) {
+  let beat = startBeat;
+  let bars = 0;
+  while (beat < endBeat - BEAT_EPS) {
+    const barBeats = beatsPerBarAt(beat, meters);
+    const step = Math.min(barStartBeat(beat, meters) + barBeats, endBeat) - beat;
+    bars += step / barBeats;
+    beat += step;
+  }
+  return bars;
+}
+function spanSegments(profile, sections) {
+  const { startBeat, endBeat } = profile.span;
+  const cuts = [startBeat, endBeat];
+  for (const section of sections) {
+    for (const beat of [section.startBeat, section.endBeat]) {
+      if (beat > startBeat + BEAT_EPS && beat < endBeat - BEAT_EPS) cuts.push(beat);
+    }
+  }
+  cuts.sort((a, b) => a - b);
+  const segments = [];
+  for (let index = 1; index < cuts.length; index += 1) {
+    const from = cuts[index - 1];
+    const to = cuts[index];
+    if (to - from > BEAT_EPS) segments.push([from, to]);
+  }
+  return segments;
+}
+function plannedPhraseSpans(profile, sections, weight, draw) {
+  const segments = spanSegments(profile, sections);
+  const pieces = profile.form.phrases.map((phrase, source) => ({
+    startBeat: phrase.startBeat,
+    endBeat: phrase.endBeat,
+    source,
+    cadence: phrase.cadence?.type ?? null
+  }));
+  const replaced = pieces.map((_, index) => !draw.prob(weight, "phraseLengths", index));
+  const spans = [];
+  for (const [segmentStart, segmentEnd] of segments) {
+    const members = pieces.map((piece, index) => ({ piece, index })).filter(
+      ({ piece }) => piece.startBeat >= segmentStart - BEAT_EPS && piece.startBeat < segmentEnd - BEAT_EPS
+    );
+    const laid = [];
+    let cursor = segmentStart;
+    for (const { piece, index } of members) {
+      const lengths = [];
+      if (replaced[index]) {
+        const bars = barsBetween(piece.startBeat, piece.endBeat, profile.meters);
+        const rounded = 2 ** Math.round(Math.log2(bars));
+        const overflows = beatAfterBars(cursor, rounded, profile.meters) > segmentEnd + BEAT_EPS;
+        let partStart = cursor;
+        for (const part of overflows ? [rounded / 2, rounded / 2] : [rounded]) {
+          const partEnd = beatAfterBars(partStart, part, profile.meters);
+          lengths.push(partEnd - partStart);
+          partStart = partEnd;
+        }
+      } else {
+        lengths.push(piece.endBeat - piece.startBeat);
+      }
+      lengths.forEach((length, part) => {
+        if (cursor >= segmentEnd - BEAT_EPS) return;
+        const end = cursor + length;
+        laid.push({
+          startBeat: cursor,
+          endBeat: Math.min(end, segmentEnd),
+          source: piece.source,
+          cadence: part === lengths.length - 1 ? piece.cadence : null
+        });
+        cursor = end;
+      });
+    }
+    const last = laid.at(-1);
+    if (last) {
+      last.endBeat = segmentEnd;
+    } else {
+      laid.push({
+        startBeat: segmentStart,
+        endBeat: segmentEnd,
+        source: spans.at(-1)?.source ?? (profile.form.phrases.length > 0 ? 0 : -1),
+        cadence: null
+      });
+    }
+    spans.push(...laid);
+  }
+  return spans;
+}
+function sectionAt(sections, beat) {
+  const index = sections.findIndex(
+    (section) => beat >= section.startBeat - BEAT_EPS && beat < section.endBeat - BEAT_EPS
+  );
+  return index < 0 ? null : index;
+}
+function phraseHolding(phrases, startBeat, endBeat) {
+  return phrases.findIndex(
+    (phrase) => startBeat >= phrase.startBeat - BEAT_EPS && endBeat <= phrase.endBeat + BEAT_EPS
+  );
+}
+function better(a, b) {
+  for (let field = 0; field < a.length; field += 1) {
+    if (a[field] !== b[field]) return a[field] > b[field];
+  }
+  return false;
+}
+function scheduleMotifs(candidates, meters) {
+  const order = [...candidates].sort((a, b) => a.startBeat - b.startBeat || a.node - b.node);
+  const count = order.length;
+  const firstFrom = (from, beat) => {
+    let low = from;
+    let high = count;
+    while (low < high) {
+      const mid = low + high >> 1;
+      if (order[mid].startBeat < beat - BEAT_EPS) low = mid + 1;
+      else high = mid;
+    }
+    return low;
+  };
+  const next = order.map((candidate, index2) => firstFrom(index2 + 1, candidate.endBeat));
+  const own = order.map(
+    (candidate) => [
+      candidate.notes,
+      metricWeight(candidate.startBeat, meters) < STRONG_WEIGHT2 ? -1 : 0,
+      1
+    ]
+  );
+  const taking = (index2) => {
+    const rest = best[next[index2]];
+    const mine = own[index2];
+    return [mine[0] + rest[0], mine[1] + rest[1], mine[2] + rest[2]];
+  };
+  const best = new Array(count + 1).fill([0, 0, 0]);
+  for (let index2 = count - 1; index2 >= 0; index2 -= 1) {
+    const taken = taking(index2);
+    const skipped = best[index2 + 1];
+    best[index2] = better(taken, skipped) ? taken : skipped;
+  }
+  const chosen = [];
+  let index = 0;
+  while (index < count) {
+    if (!better(best[index], taking(index))) {
+      chosen.push(order[index]);
+      index = next[index];
+    } else {
+      index += 1;
+    }
+  }
+  return chosen.sort((a, b) => a.node - b.node);
+}
+function selectedDerivation(graph, parentEdge, selectedAt, node) {
+  let plain = true;
+  let semitones = 0;
+  let steps = 0;
+  for (let edge = parentEdge.get(node); edge !== void 0; edge = parentEdge.get(edge.from)) {
+    const relation = edge.relation;
+    steps += 1;
+    plain &&= relation !== null && (relation.kind === "repetition" || relation.kind === "transposition" && Math.abs(relation.timeRatio - 1) <= BEAT_EPS);
+    semitones += relation?.semitones ?? 0;
+    const from = selectedAt.get(edge.from);
+    if (from === void 0) continue;
+    if (steps === 1) {
+      return { from, relation: relation === null ? null : { ...relation } };
+    }
+    if (!plain) {
+      return { from: null, relation: null };
+    }
+    const gap = (graph.nodes[node]?.startBeat ?? 0) - (graph.nodes[edge.from]?.endBeat ?? 0);
+    return {
+      from,
+      relation: {
+        kind: semitones === 0 ? "repetition" : "transposition",
+        sequence: gap >= -HUMANIZE_ADJACENCY && gap <= HUMANIZE_ADJACENCY,
+        semitones,
+        timeRatio: 1
+      }
+    };
+  }
+  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;
+  }
+  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;
+  const romans = chords.map((chord, index) => {
+    if (chord.level !== "structural" || draw.prob(preserve.harmonicFunction, "harmonicFunction", index)) {
+      return chord.roman;
+    }
+    const candidates = functionCandidates(chord.function, keys[chord.key]);
+    if (candidates === null) {
+      return chord.roman;
+    }
+    const pick = draw.range(0, candidates.length - 1, "harmonicFunction", index, "pick");
+    return candidates[pick];
+  });
+  const starts = [];
+  chords.forEach((chord, index) => {
+    const keep = index === 0 || draw.prob(preserve.harmonicRhythm, "harmonicRhythm", index);
+    const start = keep ? chord.startBeat : barStartBeat(chord.startBeat, profile.meters);
+    starts.push(index === 0 ? start : Math.max(start, starts[index - 1]));
+  });
+  const planned = [];
+  chords.forEach((chord, index) => {
+    const next = chords[index + 1];
+    const nextStart = starts[index + 1];
+    let endBeat = chord.endBeat;
+    if (next !== void 0 && nextStart !== void 0) {
+      endBeat = Math.abs(chord.endBeat - next.startBeat) <= BEAT_EPS ? nextStart : Math.min(chord.endBeat, nextStart);
+    }
+    const startBeat = starts[index];
+    if (endBeat - startBeat > BEAT_EPS) {
+      planned.push({ startBeat, endBeat, key: chord.key, roman: romans[index] });
+    }
+  });
+  return planned;
+}
+function plannedRhythm(profile, weight) {
+  const reference = profile.melody.rhythm;
+  return {
+    onsetLevels: reference.onsetLevels.map(
+      (share, level) => lerp(weight, share, NEUTRAL_ONSET_LEVELS[level])
+    ),
+    interOnsetShares: [...reference.interOnsetShares],
+    syncopation: lerp(weight, reference.syncopation, 0)
+  };
+}
+function deriveCompositionPlan(reference, opts) {
+  const profile = assertReferenceProfile(reference, "reference");
+  const asked = assertOptions(opts, "opts");
+  const preserve = readPreserve(asked.preserve);
+  const requestedRegister = asked.register === void 0 ? void 0 : readRegister(asked.register);
+  rejectSuppliedRng(asked.ctx);
+  const ctx = resolveContext(asked.ctx);
+  const draw = ctx.part("plan");
+  const melodyRegister = profile.melody.register;
+  if (profile.melody.rhythm.onsets === 0 || melodyRegister === null) {
+    throw new InvalidInputError("reference must carry melody onsets to derive a plan from");
+  }
+  const keys = plannedKeys(profile, asked.key);
+  const homeShift = mod12(
+    keys[0].scale.rootPc - (profile.harmony.keys[0]?.key.scale.rootPc ?? 0)
+  );
+  const shift = homeShift >= 6 ? homeShift - 12 : homeShift;
+  const source = { low: melodyRegister.low + shift, high: melodyRegister.high + shift };
+  if (source.low < 0 || source.high > 127) {
+    throw new InvalidInputError(
+      `the reference melody range moved to the new key leaves the MIDI range; received ${source.low}..${source.high}`
+    );
+  }
+  const target = requestedRegister ?? source;
+  const scale = source.high === source.low ? 0 : (target.high - target.low) / (source.high - source.low);
+  const offset = source.high === source.low ? (target.low + target.high) / 2 : target.low - source.low * scale;
+  const mapPitch = (pitch) => (pitch + shift) * scale + offset;
+  const neutralRegister = {
+    low: target.low,
+    high: target.high,
+    mean: (target.low + target.high) / 2
+  };
+  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;
+    const register = melody ? {
+      low: Math.round(lerp(shapeWeight, mapPitch(melody.low), neutralRegister.low)),
+      high: Math.round(lerp(shapeWeight, mapPitch(melody.high), neutralRegister.high)),
+      mean: lerp(shapeWeight, mapPitch(melody.mean), neutralRegister.mean)
+    } : { ...neutralRegister };
+    return {
+      startBeat: span.startBeat,
+      endBeat: span.endBeat,
+      section: sectionAt(sections, span.startBeat),
+      cadence: span.cadence,
+      shape: melody && shapeWeight >= SHAPE_KEEP_THRESHOLD ? melody.shape : NEUTRAL_SHAPE,
+      peakPosition: melody ? lerp(shapeWeight, melody.peakPosition, NEUTRAL_PEAK_POSITION) : NEUTRAL_PEAK_POSITION,
+      register,
+      onsetDensity: melody ? melody.onsetDensity : profile.melody.rhythm.onsetDensity,
+      motifs: []
+    };
+  });
+  const graph = profile.melody.graph;
+  const noteCount = (node) => (profile.melody.motifs[graph.nodes[node]?.motif ?? -1]?.intervals.length ?? 0) + 1;
+  assertGenerationBudget(graph.nodes.length * phrases.length, "plan motif selection", asked.budget);
+  const candidates = [];
+  graph.nodes.forEach((node, index) => {
+    const phrase = phraseHolding(phrases, node.startBeat, node.endBeat);
+    if (phrase >= 0) {
+      candidates.push({
+        node: index,
+        phrase,
+        startBeat: node.startBeat,
+        endBeat: node.endBeat,
+        notes: noteCount(index)
+      });
+    }
+  });
+  const selected = scheduleMotifs(candidates, profile.meters);
+  const selectedAt = new Map(selected.map((candidate, index) => [candidate.node, index]));
+  const parentEdge = new Map(graph.edges.map((edge) => [edge.to, edge]));
+  const motifs = selected.map((candidate, index) => {
+    const { from, relation } = selectedDerivation(graph, parentEdge, selectedAt, candidate.node);
+    const keepRelation = draw.prob(preserve.motifRelations, "motifRelations", index);
+    const keepRhythm = from === null && draw.prob(preserve.rhythm, "rhythm", index);
+    const cell = profile.melody.motifs[graph.nodes[candidate.node]?.motif ?? -1];
+    phrases[candidate.phrase]?.motifs.push(index);
+    return {
+      phrase: candidate.phrase,
+      startBeat: candidate.startBeat,
+      endBeat: candidate.endBeat,
+      notes: candidate.notes,
+      rhythm: keepRhythm && cell !== void 0 ? cell.rhythm.map((ratio) => ratio * cell.unitBeats) : null,
+      from,
+      relation: keepRelation ? relation : null
+    };
+  });
+  return {
+    planVersion: COMPOSITION_PLAN_VERSION,
+    seed: ctx.seed,
+    algorithmVersion: ctx.algorithmVersion,
+    keys,
+    meters: profile.meters.map((entry) => ({
+      startBeat: entry.startBeat,
+      ts: entry.ts.grouping === void 0 ? { ...entry.ts } : { ...entry.ts, grouping: [...entry.ts.grouping] }
+    })),
+    span: { ...profile.span },
+    sections,
+    phrases,
+    harmony: plannedHarmony(profile, keys, preserve, draw),
+    motifs,
+    rhythm: plannedRhythm(profile, preserve.rhythm)
+  };
+}
+
+// src/generate/plan/evaluate.ts
+var PEAK_POSITION_TOLERANCE = 0.2;
+var OUTLINE_POINTS = 8;
+var HELD_NOTE_BEATS = 1;
+function interiorBoundaries(plan) {
+  const beats = /* @__PURE__ */ new Set();
+  for (const phrase of plan.phrases) {
+    for (const beat of [phrase.startBeat, phrase.endBeat]) {
+      if (beat > plan.span.startBeat + BEAT_EPS && beat < plan.span.endBeat - BEAT_EPS) {
+        beats.add(beat);
+      }
+    }
+  }
+  return [...beats].sort((a, b) => a - b);
+}
+function restsOf(melody, plan) {
+  const rests = [];
+  let reach = plan.span.startBeat;
+  for (const note2 of [...melody].sort((a, b) => a.startBeat - b.startBeat)) {
+    if (note2.startBeat > reach + BEAT_EPS) {
+      rests.push({ startBeat: reach, endBeat: note2.startBeat });
+    }
+    reach = Math.max(reach, note2.startBeat + note2.durationBeat);
+  }
+  if (plan.span.endBeat > reach + BEAT_EPS) {
+    rests.push({ startBeat: reach, endBeat: plan.span.endBeat });
+  }
+  return rests;
+}
+function phraseBoundaryViolations(melody, plan) {
+  const rests = restsOf(melody, plan);
+  const violations = [];
+  for (const beat of interiorBoundaries(plan)) {
+    const pulse2 = pulseBeats(meterAt(beat, plan.meters));
+    const held = melody.some(
+      (note2) => note2.durationBeat >= HELD_NOTE_BEATS - BEAT_EPS && Math.abs(note2.startBeat + note2.durationBeat - beat) <= pulse2 + BEAT_EPS
+    );
+    const rested = rests.some(
+      (rest) => rest.endBeat - rest.startBeat >= pulse2 - BEAT_EPS && rest.startBeat <= beat + pulse2 + BEAT_EPS && rest.endBeat >= beat - pulse2 - BEAT_EPS
+    );
+    if (!held && !rested) {
+      violations.push({
+        kind: "phraseBoundary",
+        severity: "error",
+        atBeat: beat,
+        expected: `a note of at least ${HELD_NOTE_BEATS} beat(s) ending, or a rest of at least ${pulse2} beat(s), within ${pulse2} beat(s)`,
+        actual: "neither",
+        rationale: `the plan places a phrase boundary at beat ${beat}, which the candidate does not mark`
+      });
+    }
+  }
+  return violations;
+}
+function spanViolation(melody, plan) {
+  const end = melody.reduce((max, note2) => Math.max(max, note2.startBeat + note2.durationBeat), 0);
+  if (end <= plan.span.endBeat + BEAT_EPS) {
+    return [];
+  }
+  return [
+    {
+      kind: "span",
+      severity: "error",
+      atBeat: plan.span.endBeat,
+      expected: `ending by beat ${plan.span.endBeat}`,
+      actual: `ending at beat ${end}`,
+      rationale: "the candidate's last note runs past the plan's span"
+    }
+  ];
+}
+function phraseLines(melody, plan) {
+  return plan.phrases.map(
+    (phrase) => melody.flatMap(
+      (note2, index) => note2.startBeat >= phrase.startBeat - BEAT_EPS && note2.startBeat < phrase.endBeat - BEAT_EPS ? [index] : []
+    )
+  );
+}
+function cadenceViolations(melody, plan, timeline, lines) {
+  const violations = [];
+  plan.phrases.forEach((phrase, index) => {
+    if (phrase.cadence === null) {
+      return;
+    }
+    const last = lines[index]?.at(-1);
+    const note2 = last === void 0 ? void 0 : melody[last];
+    const allowed = note2 === void 0 ? [] : cadencePitchClasses(plan, timeline, phrase.cadence, note2.startBeat);
+    if (note2 !== void 0 && (allowed === null || allowed.includes(pitchClassOf(note2.pitch)))) {
+      return;
+    }
+    violations.push({
+      kind: "cadence",
+      severity: "error",
+      atBeat: phrase.endBeat,
+      expected: `a closing note on pitch class ${(allowed ?? []).join(" or ")} for a ${phrase.cadence} cadence`,
+      actual: note2 === void 0 ? "no note" : `pitch ${note2.pitch}`,
+      rationale: `the phrase ending at beat ${phrase.endBeat} is planned to close on a ${phrase.cadence} cadence`
+    });
+  });
+  return violations;
+}
+function harmonyViolations(melody, plan, timeline, lines) {
+  const misfits = planHarmonyMisfits(plan, timeline);
+  const violations = [];
+  for (const line of lines) {
+    const read = misfits(line.map((index) => melody[index]));
+    read.forEach((kinds, at2) => {
+      if (kinds === null) {
+        return;
+      }
+      const note2 = melody[line[at2]];
+      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" && timeline.at(note2.startBeat) !== null;
+      violations.push({
+        kind: "harmony",
+        severity: derived ? "warning" : "error",
+        atBeat: note2.startBeat,
+        expected: strong ? "a chord tone or an ornamental tone" : "a chord tone, an ornamental tone, or a scale tone",
+        actual: kinds.length === 0 ? "no harmonic label" : kinds.join(", "),
+        rationale: derived ? `the note at beat ${note2.startBeat} sits in a derived statement, whose transformation takes precedence over the harmony` : `the note at beat ${note2.startBeat} does not fit the planned harmony`
+      });
+    });
+  }
+  return violations;
+}
+function notesInRange(melody, startBeat, endBeat) {
+  return melody.filter(
+    (note2) => note2.startBeat >= startBeat - BEAT_EPS && note2.startBeat < endBeat - BEAT_EPS
+  );
+}
+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;
+  const outside = (pitch) => pitch < low || pitch > high;
+  const backward = relation.kind === "retrograde" || relation.kind === "retrogradeInversion";
+  const cell = clipStatement(
+    source.map((note2) => ({
+      pitch: note2.pitch,
+      startBeat: note2.startBeat,
+      durationBeat: note2.durationBeat
+    })),
+    sourceEnd
+  );
+  const replays = relationLevels(relation.kind).map((level) => {
+    const notes = clipStatement(
+      replayAt(cell, relation, level, statement.startBeat, key),
+      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) {
+    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 = compared[i];
+      if (i > 0) {
+        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) {
+        continue;
+      }
+      const origin = source[backward ? cell.length - 1 - i : i];
+      forced += 1;
+      holds = closing.has(got) || origin !== void 0 && closing.has(origin) || away === fewestOutside && outside(want.pitch);
+    }
+    const distance = Math.abs(level - planned);
+    const nearer = best === null || distance < Math.abs(best.level - planned) || distance === Math.abs(best.level - planned) && level < best.level;
+    if (holds && nearer) {
+      best = { level, forced };
+    }
+  }
+  return best;
+}
+function motifDerivationViolations(melody, plan, closing) {
+  const keyAt = planKeyAt(plan);
+  const errors = [];
+  const warnings = [];
+  for (const statement of plan.motifs) {
+    if (statement.from === null) {
+      continue;
+    }
+    const source = plan.motifs[statement.from];
+    const sourceNotes = notesInRange(melody, source.startBeat, source.endBeat);
+    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",
+        severity: "error",
+        atBeat: statement.startBeat,
+        expected: relation === null ? "a variation" : relation.kind,
+        actual: "no notes to compare",
+        rationale
+      });
+      continue;
+    }
+    const sourceCut = sourceKept < source.endBeat - BEAT_EPS;
+    const derivedCut = derivedKept < statement.endBeat - BEAT_EPS;
+    if (relation === null) {
+      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",
+          severity: "error",
+          atBeat: statement.startBeat,
+          expected: `a variation (melodicSimilarity >= ${DEFAULT_VARIATION_THRESHOLD})`,
+          actual: `melodicSimilarity ${similarity.toFixed(3)}`,
+          rationale
+        });
+      }
+      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(
+      kept,
+      notesInRange(melody, statement.startBeat, derivedKept),
+      statement,
+      sourceKept,
+      derivedKept,
+      sourceCut,
+      plan,
+      scaleOf(keyAt(statement.startBeat)),
+      closing
+    );
+    const planned = relation.kind === "tonalTransposition" ? relation.degrees ?? 0 : relation.semitones;
+    if (replay === null) {
+      errors.push({
+        kind: "motifDerivation",
+        severity: "error",
+        atBeat: statement.startBeat,
+        expected: relation.kind,
+        actual: "no pitch level replays the source",
+        rationale
+      });
+    } else if (replay.level !== planned || replay.forced > 0) {
+      warnings.push({
+        kind: "motifDisplaced",
+        severity: "warning",
+        atBeat: statement.startBeat,
+        expected: `${relation.kind} at level ${planned} with every pitch replayed`,
+        actual: `level ${replay.level}, ${replay.forced} excused note(s)`,
+        rationale: `the statement at beat ${statement.startBeat} carries out its planned derivation at another pitch level or with notes excused`
+      });
+    }
+  }
+  return { errors, warnings };
+}
+function phraseAt(plan, beat) {
+  return plan.phrases.find(
+    (phrase) => beat >= phrase.startBeat - BEAT_EPS && beat < phrase.endBeat - BEAT_EPS
+  );
+}
+function registerViolations(melody, plan) {
+  const violations = [];
+  for (const note2 of melody) {
+    const phrase = phraseAt(plan, note2.startBeat);
+    if (phrase === void 0) {
+      continue;
+    }
+    if (note2.pitch < phrase.register.low || note2.pitch > phrase.register.high) {
+      violations.push({
+        kind: "register",
+        severity: "error",
+        atBeat: note2.startBeat,
+        expected: `a pitch within [${phrase.register.low}, ${phrase.register.high}]`,
+        actual: `pitch ${note2.pitch}`,
+        rationale: `the note at beat ${note2.startBeat} falls outside its phrase's planned register`
+      });
+    }
+  }
+  return violations;
+}
+function planOutline(phrase) {
+  const amplitude = (phrase.register.high - phrase.register.low) / 2;
+  const outline = [];
+  for (let k = 0; k < OUTLINE_POINTS; k += 1) {
+    const t = (k + 0.5) / OUTLINE_POINTS;
+    outline.push(
+      phrase.register.mean + plannedContourAt(phrase.shape, phrase.peakPosition, t) * amplitude
+    );
+  }
+  return outline;
+}
+function planContourPhrase(phrase) {
+  return {
+    shape: phrase.shape,
+    low: phrase.register.low,
+    high: phrase.register.high,
+    outline: planOutline(phrase)
+  };
+}
+function planRegisterPlan(plan) {
+  const phrases = plan.phrases.map((phrase) => ({
+    low: phrase.register.low,
+    high: phrase.register.high,
+    mean: phrase.register.mean,
+    peakPosition: phrase.peakPosition
+  }));
+  let weighted = 0;
+  let weight = 0;
+  for (const phrase of plan.phrases) {
+    const length = phrase.endBeat - phrase.startBeat;
+    weighted += phrase.register.mean * length;
+    weight += length;
+  }
+  return { phrases, mean: weight > 0 ? weighted / weight : null };
+}
+function planRhythmReading(plan) {
+  const hasOnsets = plan.rhythm.onsetLevels.some((share) => share > 0);
+  return {
+    onsets: hasOnsets ? 1 : 0,
+    onsetLevels: plan.rhythm.onsetLevels,
+    barPositions: [],
+    interOnsetShares: plan.rhythm.interOnsetShares,
+    syncopation: plan.rhythm.syncopation
+  };
+}
+function peakPositionWarnings(plan, readings) {
+  const violations = [];
+  plan.phrases.forEach((phrase, index) => {
+    const reading = readings[index];
+    if (reading == null) {
+      return;
+    }
+    const drift = Math.abs(reading.peakPosition - phrase.peakPosition);
+    if (drift > PEAK_POSITION_TOLERANCE) {
+      violations.push({
+        kind: "peakPosition",
+        severity: "warning",
+        atBeat: phrase.startBeat,
+        expected: `a peak position within ${PEAK_POSITION_TOLERANCE} of ${phrase.peakPosition}`,
+        actual: `${reading.peakPosition}`,
+        rationale: `the phrase starting at beat ${phrase.startBeat} places its melodic peak further from the planned position than the tolerance allows`
+      });
+    }
+  });
+  return violations;
+}
+function lineMeanOf(melody) {
+  let weighted = 0;
+  let total = 0;
+  for (const note2 of melody) {
+    weighted += note2.pitch * note2.durationBeat;
+    total += note2.durationBeat;
+  }
+  return total > 0 ? weighted / total : null;
+}
+function planDensity(plan) {
+  let weighted = 0;
+  let bars = 0;
+  for (const phrase of plan.phrases) {
+    const span = barSpanOf(phrase.startBeat, phrase.endBeat, plan.meters);
+    weighted += phrase.onsetDensity * span;
+    bars += span;
+  }
+  return { onsets: 1, onsetDensity: bars > 0 ? weighted / bars : 0 };
+}
+function evaluateComposition(melody, plan, opts) {
+  assertCompositionPlan(plan, "evaluated plan");
+  const { budget } = assertOptions(opts, "evaluate options");
+  const notes = [
+    ...assertNoteEvents(melody, "evaluated melody", { budget, allowNonPositiveDuration: true })
+  ].sort((a, b) => a.startBeat - b.startBeat);
+  const timeline = planChordTimeline(plan);
+  const lines = phraseLines(notes, plan);
+  const closing = new Set(
+    lines.flatMap((line) => line.length === 0 ? [] : [notes[line.at(-1)]])
+  );
+  const derivations = motifDerivationViolations(notes, plan, closing);
+  const lineMean = lineMeanOf(notes);
+  const readings = plan.phrases.map(
+    (phrase) => phraseMelody(notes, phrase.startBeat, phrase.endBeat, lineMean ?? 0, plan.meters, budget)
+  );
+  const violations = [
+    ...spanViolation(notes, plan),
+    ...phraseBoundaryViolations(notes, plan),
+    ...cadenceViolations(notes, plan, timeline, lines),
+    ...harmonyViolations(notes, plan, timeline, lines),
+    ...registerViolations(notes, plan),
+    ...derivations.errors,
+    ...derivations.warnings,
+    ...peakPositionWarnings(plan, readings)
+  ];
+  const rhythm = analyzeRhythm(notes, {
+    meters: plan.meters,
+    totalBeats: plan.span.endBeat,
+    budget
+  });
+  const target = planRhythmReading(plan);
+  const fit = {
+    contour: contourSimilarity(plan.phrases.map(planContourPhrase), readings),
+    register: registerSimilarity(planRegisterPlan(plan), { phrases: readings, mean: lineMean }),
+    onset: onsetSimilarity(target, rhythm),
+    duration: durationSimilarity(target, rhythm),
+    syncopation: syncopationSimilarity(target, rhythm),
+    density: densitySimilarity(planDensity(plan), rhythm)
+  };
+  return { violations, fit };
+}
+
+// src/generate/progression/index.ts
+var DEFAULT_TS6 = { numerator: 4, denominator: 4 };
+var PROG_STYLES = Object.freeze(["minimal", "dance", "idol", "rock"]);
+var BORROWED_DEGREES = Object.freeze({
+  /** Flat submediant: bVI. */
+  bVI: 8,
+  /** Flat subtonic: bVII. */
+  bVII: 10,
+  /** Flat mediant: bIII. */
+  bIII: 11,
+  /** Minor subdominant borrowed from the parallel minor: iv. */
+  iv: 12,
+  /** Neapolitan: bII. */
+  bII: 13,
+  /** Sharp subdominant, the diminished #IV. */
+  sharpIV: 14
+});
 var PRESETS = [
   {
     id: "fourChordPop",
@@ -5158,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";
@@ -5173,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;
@@ -5210,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) {
@@ -5230,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) {
@@ -5245,6 +7550,7 @@ function generateProgression(opts) {
   const cycle = resolveCycle(
     preset?.degrees ?? [0],
     key,
+    tonic,
     ext,
     preset?.functional === "cadenceStrong"
   );
@@ -5277,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)) {
@@ -5318,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;
 }
@@ -5356,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)) {
@@ -5369,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"
+        });
       }
     }
   }
@@ -5411,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) => {
@@ -5429,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;
@@ -5469,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;
@@ -5569,10 +7893,14 @@ export {
   thin,
   double,
   halfTime,
+  halfTimeFigure,
   doubleTime,
+  doubleTimeFigure,
   syncopate,
   ornamentBy,
   deform,
+  resolveDials,
+  deformFigure,
   withinCeiling,
   isLickMaterial,
   BASS_LICKS,
@@ -5603,8 +7931,14 @@ export {
   motifToNoteEvents,
   transformMotif,
   developMotif,
+  COMPOSITION_PLAN_VERSION,
+  assertCompositionPlan,
+  planTimeline,
+  generateMelody,
   ORNAMENT_STYLES,
   ornament,
+  deriveCompositionPlan,
+  evaluateComposition,
   BORROWED_DEGREES,
   progressions,
   progressionsByStyle,
@@ -5618,4 +7952,4 @@ export {
   generateRhythm,
   rhythmDensity
 };
-//# sourceMappingURL=chunk-Q6LFSAKV.js.map
+//# sourceMappingURL=chunk-FK3DGAIZ.js.map