@libraz/libcantus 1.0.1 → 1.2.0

package/dist/chunk-HYJJ2V2I.js

@@ -0,0 +1,2294 @@
+import {
+  HUMANIZE_ADJACENCY,
+  adjacent,
+  analyzeTimeline,
+  analyzeVoice,
+  assertChordTimeline,
+  attachPivots,
+  barGridStart,
+  chordTimelineFromNotes,
+  clamp01,
+  combineEvidence,
+  detectCadence,
+  detectCadences,
+  dirtySlotsFor,
+  firstSoundingBeat,
+  floorMod,
+  functionOf,
+  gridForNotes,
+  harmonicNovelty,
+  hasEnded,
+  isAppliedDominant,
+  isCadentialSixFour,
+  keyLookup,
+  keyScaleAt,
+  keyTimelineFromNotes,
+  lastBarOf,
+  prevailingKeyOf,
+  sameInstant,
+  segmentStartingAt,
+  sliceBars,
+  weightSimilarity,
+  windowWeights
+} from "./chunk-H2KJHBW4.js";
+import {
+  PROFILE_WEIGHTS,
+  chordPitchClasses,
+  evaluateSafety,
+  isDominantChordOf,
+  keySignatureFifths,
+  majorKey,
+  resolveKey,
+  scaleOf,
+  scaleTonesInDegreeOrder
+} from "./chunk-RFIBF2RR.js";
+import {
+  BEAT_EPS,
+  InvalidInputError,
+  assertArray,
+  assertFiniteNumber,
+  assertFunction,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvents,
+  assertOneOf,
+  assertOptions,
+  assertPositiveInt,
+  assertRange,
+  assertRecord,
+  barIndexAt,
+  barPositionToBeat,
+  beatsPerBarAt,
+  describeRejected,
+  isStrongBeat,
+  midiToNote,
+  pitchClassOf,
+  resolveMeters,
+  spelledInterval
+} from "./chunk-AGOVW7U6.js";
+
+// src/analyze/arrange/internal.ts
+var MAX_LANE_LEAP = 24;
+function covers(note, beat) {
+  return beat >= note.startBeat - BEAT_EPS && beat < note.endBeat - BEAT_EPS;
+}
+function isPercussion(role) {
+  return role === "drums";
+}
+var TRACK_ROLE_TABLE = {
+  melody: true,
+  harmony: true,
+  bass: true,
+  drums: true,
+  other: true
+};
+var TRACK_ROLES = Object.keys(TRACK_ROLE_TABLE);
+function trackRoleOf(role, name) {
+  return role === void 0 ? "other" : assertOneOf(role, TRACK_ROLES, name);
+}
+var DEFAULT_PROFILE = "pop";
+var SAFETY_PROFILES = Object.keys(PROFILE_WEIGHTS);
+function arrangementProfile(profile) {
+  return assertOneOf(profile ?? DEFAULT_PROFILE, SAFETY_PROFILES, "arrangement profile");
+}
+function assertTrackNotes(tracks, options) {
+  assertArray(tracks, "arrangement tracks");
+  let noteCount = 0;
+  for (let index = 0; index < tracks.length; index += 1) {
+    const notes = tracks[index]?.notes;
+    if (!Array.isArray(notes)) {
+      throw new InvalidInputError(
+        `tracks[${index}].notes must be an array; received ${typeof notes}`
+      );
+    }
+    assertNoteEvents(notes, `tracks[${index}].notes`, options);
+    noteCount += notes.length;
+  }
+  return noteCount;
+}
+function assertGivenTimeline(timeline, name) {
+  if (timeline !== void 0) {
+    assertChordTimeline(timeline, name);
+  }
+}
+function assertGivenKeys(keys, name) {
+  if (keys === void 0) {
+    return;
+  }
+  if (!Array.isArray(keys)) {
+    throw new InvalidInputError(
+      `${name} must be an array of key regions; received ${describeRejected(keys)}`
+    );
+  }
+  for (let index = 0; index < keys.length; index += 1) {
+    const region = keys[index];
+    if (typeof region !== "object" || region === null) {
+      throw new InvalidInputError(
+        `${name}[${index}] must be a key region; received ${describeRejected(region)}`
+      );
+    }
+    assertFiniteNumber(region.startBeat, `${name}[${index}].startBeat`);
+    assertFiniteNumber(region.endBeat, `${name}[${index}].endBeat`);
+    if (region.key === void 0 || region.key === null || typeof region.key !== "string" && typeof region.key !== "object") {
+      throw new InvalidInputError(
+        `${name}[${index}].key must name a key; received ${describeRejected(region.key)}`
+      );
+    }
+    resolveKey(region.key);
+  }
+}
+function harmonyTrackSet(harmonyTracks, tracks, name = "harmonyTracks") {
+  if (harmonyTracks === void 0) {
+    return void 0;
+  }
+  const only = /* @__PURE__ */ new Set();
+  for (let index = 0; index < harmonyTracks.length; index += 1) {
+    const value = harmonyTracks[index];
+    if (value === void 0 || !Number.isFinite(value)) {
+      throw new InvalidInputError(`${name}[${index}] must be a track index; received ${value}`);
+    }
+    const track = Math.trunc(value);
+    if (track < 0 || track >= tracks.length) {
+      throw new InvalidInputError(
+        `${name}[${index}] ${track} is outside the arrangement's ${tracks.length} tracks`
+      );
+    }
+    if (isPercussion(tracks[track]?.role)) {
+      throw new InvalidInputError(
+        `${name}[${index}] ${track} names a percussion track, whose pitches state no harmony`
+      );
+    }
+    only.add(track);
+  }
+  return only;
+}
+function poolNotes(tracks, only) {
+  const notes = [];
+  for (let index = 0; index < tracks.length; index += 1) {
+    const track = tracks[index];
+    if (track === void 0 || isPercussion(track.role)) {
+      continue;
+    }
+    if (only !== void 0 && !only.has(index)) {
+      continue;
+    }
+    for (const note of track.notes) {
+      if (note.durationBeat > 0) {
+        notes.push(note);
+      }
+    }
+  }
+  return notes;
+}
+function splitIntoSubVoices(ordered) {
+  const lanes = [];
+  const attachNearest = (note, excluded = /* @__PURE__ */ new Set()) => {
+    let best = -1;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let bestEnd = Number.NEGATIVE_INFINITY;
+    for (let lane = 0; lane < lanes.length; lane += 1) {
+      if (excluded.has(lane)) {
+        continue;
+      }
+      const last = lanes[lane]?.[(lanes[lane]?.length ?? 0) - 1];
+      if (last === void 0) {
+        continue;
+      }
+      const end = last.startBeat + last.durationBeat;
+      if (!hasEnded(end, note.startBeat)) {
+        continue;
+      }
+      const distance = Math.abs(last.pitch - note.pitch);
+      if (distance > MAX_LANE_LEAP) {
+        continue;
+      }
+      if (distance < bestDistance || distance === bestDistance && end > bestEnd) {
+        best = lane;
+        bestDistance = distance;
+        bestEnd = end;
+      }
+    }
+    if (best >= 0) {
+      lanes[best]?.push(note);
+    }
+    return best;
+  };
+  for (let start = 0; start < ordered.length; ) {
+    const onset = ordered[start]?.startBeat ?? 0;
+    let end = start + 1;
+    while (end < ordered.length && sameInstant(ordered[end]?.startBeat ?? 0, onset)) {
+      end += 1;
+    }
+    const block = ordered.slice(start, end);
+    if (block.length > 1) {
+      const freeLanes = lanes.map((lane, index) => ({ index, last: lane[lane.length - 1] })).filter(
+        (entry) => entry.last !== void 0 && hasEnded(entry.last.startBeat + entry.last.durationBeat, onset)
+      ).sort((a, b) => a.last.pitch - b.last.pitch);
+      const assignment = pairWithFreeLanes(block, freeLanes);
+      const taken = new Set(
+        assignment.filter((lane) => lane !== void 0)
+      );
+      for (let index = 0; index < block.length; index += 1) {
+        const note = block[index];
+        if (note === void 0) {
+          continue;
+        }
+        const lane = assignment[index];
+        if (lane !== void 0) {
+          lanes[lane]?.push(note);
+          continue;
+        }
+        const attached = attachNearest(note, taken);
+        if (attached < 0) {
+          lanes.push([note]);
+        } else {
+          taken.add(attached);
+        }
+      }
+    } else {
+      const note = block[0];
+      if (note !== void 0 && attachNearest(note) < 0) {
+        lanes.push([note]);
+      }
+    }
+    start = end;
+  }
+  return lanes;
+}
+function pairWithFreeLanes(block, freeLanes) {
+  const noteCount = block.length;
+  const laneCount = freeLanes.length;
+  const assignment = new Array(noteCount).fill(void 0);
+  if (laneCount === 0) {
+    return assignment;
+  }
+  const width = laneCount + 1;
+  const cost = new Float64Array((noteCount + 1) * width);
+  const step = new Uint8Array((noteCount + 1) * width);
+  for (let i = 1; i <= noteCount; i += 1) {
+    cost[i * width] = i * MAX_LANE_LEAP;
+    step[i * width] = 2;
+  }
+  for (let i = 1; i <= noteCount; i += 1) {
+    for (let j = 1; j <= laneCount; j += 1) {
+      let best = cost[i * width + j - 1] ?? 0;
+      let choice = 0;
+      const unpaired = (cost[(i - 1) * width + j] ?? 0) + MAX_LANE_LEAP;
+      if (unpaired < best) {
+        best = unpaired;
+        choice = 2;
+      }
+      const note = block[i - 1];
+      const lane = freeLanes[j - 1];
+      if (note !== void 0 && lane !== void 0) {
+        const distance = Math.abs(lane.last.pitch - note.pitch);
+        const paired = (cost[(i - 1) * width + j - 1] ?? 0) + distance;
+        if (distance <= MAX_LANE_LEAP && paired < best) {
+          best = paired;
+          choice = 1;
+        }
+      }
+      cost[i * width + j] = best;
+      step[i * width + j] = choice;
+    }
+  }
+  for (let i = noteCount, j = laneCount; i > 0; ) {
+    if (j === 0 || step[i * width + j] === 2) {
+      i -= 1;
+    } else if (step[i * width + j] === 1) {
+      assignment[i - 1] = freeLanes[j - 1]?.index;
+      i -= 1;
+      j -= 1;
+    } else {
+      j -= 1;
+    }
+  }
+  return assignment;
+}
+function lastStartingAtOrBefore(sounding, beat) {
+  let low = 0;
+  let high = sounding.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if ((sounding[middle]?.startBeat ?? Number.POSITIVE_INFINITY) <= beat + BEAT_EPS) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low - 1;
+}
+function prepareTracks(tracks) {
+  let nextId = 0;
+  return tracks.map((track, index) => {
+    const ordered = track.notes.map((note, originalIndex) => ({ note, originalIndex })).filter(({ note }) => note.durationBeat > 0).sort((a, b) => a.note.startBeat - b.note.startBeat || a.note.pitch - b.note.pitch).map(({ note, originalIndex }) => ({ ...note, id: nextId++, originalIndex }));
+    const voices = splitIntoSubVoices(ordered).map((voice) => {
+      const sounding = voice.map((note, i) => {
+        const prev = i > 0 ? voice[i - 1] : void 0;
+        const prevEnd = prev === void 0 ? void 0 : prev.startBeat + prev.durationBeat;
+        const contiguous = prevEnd !== void 0 && adjacent(prevEnd, note.startBeat);
+        return {
+          id: note.id,
+          originalIndex: note.originalIndex,
+          pitch: note.pitch,
+          prevPitch: contiguous ? prev?.pitch : void 0,
+          startBeat: note.startBeat,
+          endBeat: note.startBeat + note.durationBeat
+        };
+      });
+      return {
+        voice,
+        sounding,
+        at: (beat) => {
+          const candidate = sounding[lastStartingAtOrBefore(sounding, beat)];
+          return candidate !== void 0 && covers(candidate, beat) ? candidate : void 0;
+        }
+      };
+    });
+    return {
+      name: track.name ?? `track ${index + 1}`,
+      role: trackRoleOf(track.role, `tracks[${index}].role`),
+      trackIndex: index,
+      voices
+    };
+  });
+}
+
+// src/analyze/arrange/tracks.ts
+function withGivenKeys(result, given) {
+  if (given === void 0) {
+    return result;
+  }
+  return { ...result, keys: given, prevailingKey: prevailingKeyOf(given) ?? result.prevailingKey };
+}
+function callerTimeline(timeline, key, given, pooled, meters, budget) {
+  const chartEnd = timeline.segments.reduce((end, segment) => Math.max(end, segment.endBeat), 0);
+  const soundingEnd = pooled.reduce(
+    (end, note) => Math.max(end, note.startBeat + note.durationBeat),
+    0
+  );
+  const totalBeats = Math.max(chartEnd, soundingEnd);
+  const { startBeat: musicStart } = gridForNotes(pooled, beatsPerBarAt(0, meters));
+  const keys = given ?? attachPivots(
+    key !== void 0 ? [{ startBeat: musicStart, endBeat: totalBeats, key: resolveKey(key), confidence: 1 }] : keyTimelineFromNotes(pooled, { meters, totalBeats, budget }),
+    timeline.segments
+  );
+  return {
+    timeline,
+    keys,
+    prevailingKey: prevailingKeyOf(keys) ?? resolveKey(majorKey(0)),
+    segmentConfidence: timeline.segments.map(() => 0)
+  };
+}
+function soundingVoicesAt(prepared, beat) {
+  const out = [];
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track || isPercussion(track.role)) {
+      continue;
+    }
+    for (let v = 0; v < track.voices.length; v += 1) {
+      const note = track.voices[v]?.at(beat);
+      if (note === void 0) {
+        continue;
+      }
+      const snap = { pitch: note.pitch };
+      const previous = sameInstant(note.startBeat, beat) ? note.prevPitch : note.pitch;
+      if (previous !== void 0) {
+        snap.prevPitch = previous;
+      }
+      out.push({ track: t, voice: v, trackIndex: track.trackIndex, note, snapshot: snap });
+    }
+  }
+  return out;
+}
+function otherVoicesSounding(prepared, excludeTrack, excludeVoice, beat, cache) {
+  const sounding = cache.get(beat) ?? soundingVoicesAt(prepared, beat);
+  cache.set(beat, sounding);
+  return sounding.filter(({ track, voice }) => track !== excludeTrack || voice !== excludeVoice);
+}
+function conflictPartner(sounding, reasons) {
+  const partner = {
+    trackIndex: sounding.trackIndex,
+    noteId: sounding.note.id,
+    reasons
+  };
+  if (sounding.note.originalIndex !== void 0) {
+    partner.originalIndex = sounding.note.originalIndex;
+  }
+  return partner;
+}
+function snapshotsOf(voices) {
+  return voices.map(({ snapshot }) => snapshot);
+}
+function analyzePolyphony(notes, chordAtBeat, key) {
+  const passage = assertNoteEvents(notes, "notes", { allowNonPositiveDuration: true });
+  assertFunction(chordAtBeat, "chordAtBeat");
+  const prepared = prepareTracks([{ notes: [...passage] }]);
+  const track = prepared[0];
+  assertGenerationBudget(
+    passage.length * (track?.voices.length ?? 0),
+    "polyphony note-voice comparisons"
+  );
+  const soundingCache = /* @__PURE__ */ new Map();
+  const byIndex = /* @__PURE__ */ new Map();
+  for (let v = 0; v < (track?.voices.length ?? 0); v += 1) {
+    const subVoice = track?.voices[v];
+    if (subVoice === void 0) {
+      continue;
+    }
+    const analyzed = analyzeVoice(
+      subVoice.voice,
+      chordAtBeat,
+      key,
+      (beat) => snapshotsOf(otherVoicesSounding(prepared, 0, v, beat, soundingCache))
+    );
+    for (const note of analyzed) {
+      if (note.originalIndex !== void 0) {
+        const { originalIndex, ...annotation } = note;
+        byIndex.set(originalIndex, { ...annotation, noteId: originalIndex });
+      }
+    }
+  }
+  return notes.map((note, index) => {
+    const analyzed = byIndex.get(index);
+    if (analyzed !== void 0) {
+      return analyzed;
+    }
+    const [only] = analyzeVoice([{ ...note, id: index }], chordAtBeat, key);
+    return only ?? {
+      noteId: index,
+      pitch: note.pitch,
+      startBeat: note.startBeat,
+      durationBeat: note.durationBeat,
+      labels: []
+    };
+  });
+}
+function firstSegmentAfter(timeline, beat) {
+  let low = 0;
+  let high = timeline.segments.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if ((timeline.segments[middle]?.startBeat ?? Number.POSITIVE_INFINITY) <= beat + BEAT_EPS) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+function evaluationBeats(note, timeline) {
+  const noteEnd = note.startBeat + note.durationBeat;
+  const beats = [note.startBeat];
+  for (let i = firstSegmentAfter(timeline, note.startBeat); i < timeline.segments.length; i += 1) {
+    const start = timeline.segments[i]?.startBeat;
+    if (start === void 0 || start >= noteEnd - BEAT_EPS) {
+      break;
+    }
+    beats.push(start);
+  }
+  return beats;
+}
+function analyzeArrangement(tracks, opts = {}) {
+  return analyzeArrangementWith(tracks, opts).analysis;
+}
+function analyzeArrangementWith(tracks, opts = {}, previous, dirty) {
+  const meters = resolveMeters(opts, "arrangement meters");
+  const budget = opts.budget;
+  const noteOptions = { allowNonPositiveDuration: true, budget };
+  if (opts.pickupBeats !== void 0) {
+    assertRange(opts.pickupBeats, 0, Number.MAX_SAFE_INTEGER, "arrangement pickupBeats");
+    noteOptions.minStartBeat = -opts.pickupBeats;
+  }
+  assertArray(tracks, "arrangement tracks");
+  assertGenerationBudget(tracks.length, "arrangement tracks", budget);
+  const noteCount = assertTrackNotes(tracks, noteOptions);
+  assertGenerationBudget(noteCount, "arrangement notes", budget);
+  const profile = arrangementProfile(opts.profile);
+  const minSeverity = opts.minSeverity === void 0 ? 1 /* Warning */ : assertInteger(
+    opts.minSeverity,
+    "arrangement minSeverity",
+    0 /* Safe */,
+    2 /* Dissonant */
+  );
+  assertGivenTimeline(opts.timeline, "arrangement timeline");
+  assertGivenKeys(opts.keys, "arrangement keys");
+  const harmonyTracks = harmonyTrackSet(opts.harmonyTracks, tracks);
+  const prepared = prepareTracks(tracks);
+  const voiceCount = prepared.reduce((sum, track) => sum + track.voices.length, 0);
+  assertGenerationBudget(noteCount * voiceCount, "arrangement note-voice comparisons", budget);
+  const pooled = poolNotes(tracks, harmonyTracks);
+  let evidence;
+  let inferred;
+  if (opts.timeline === void 0) {
+    const run = analyzeTimeline(
+      pooled,
+      {
+        key: opts.key,
+        meters,
+        pickupBeats: opts.pickupBeats,
+        harmonicRhythm: opts.harmonicRhythm,
+        budget
+      },
+      previous,
+      dirty
+    );
+    evidence = run.evidence;
+    inferred = withGivenKeys(run.result, opts.keys);
+  } else {
+    inferred = callerTimeline(opts.timeline, opts.key, opts.keys, pooled, meters, budget);
+  }
+  const { timeline, keys, prevailingKey, segmentConfidence } = inferred;
+  const keyAt = keyLookup(keys, prevailingKey);
+  const scaleAt = (beat) => scaleOf(keyAt(beat));
+  const cadences = detectCadences(timeline, scaleAt);
+  const soundingCache = /* @__PURE__ */ new Map();
+  const trackAnalyses = [];
+  const conflicts = [];
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track) {
+      continue;
+    }
+    if (isPercussion(track.role)) {
+      trackAnalyses.push({ name: track.name, role: track.role, notes: [] });
+      continue;
+    }
+    const notes = [];
+    for (let v = 0; v < track.voices.length; v += 1) {
+      const subVoice = track.voices[v];
+      if (!subVoice) {
+        continue;
+      }
+      const analyzed = analyzeVoice(
+        subVoice.voice,
+        timeline.at,
+        scaleAt,
+        (beat) => snapshotsOf(otherVoicesSounding(prepared, t, v, beat, soundingCache))
+      );
+      for (const note of analyzed) {
+        notes.push({ ...note, trackIndex: track.trackIndex });
+      }
+      const labelsById = new Map(analyzed.map((note) => [note.noteId, note.labels]));
+      for (let noteIndex = 0; noteIndex < subVoice.voice.length; noteIndex += 1) {
+        const note = subVoice.voice[noteIndex];
+        const preparedNote = subVoice.sounding[noteIndex];
+        if (note === void 0 || preparedNote === void 0) {
+          continue;
+        }
+        for (const beat of evaluationBeats(note, timeline)) {
+          const atOnset = sameInstant(beat, note.startBeat);
+          const others = otherVoicesSounding(prepared, t, v, beat, soundingCache);
+          const safetyQuery = {
+            profile,
+            candidatePitch: note.pitch,
+            prevPitch: atOnset ? preparedNote.prevPitch : note.pitch,
+            chord: timeline.at(beat),
+            key: scaleAt(beat),
+            otherVoices: snapshotsOf(others),
+            strongBeat: isStrongBeat(beat, meters)
+          };
+          let result = evaluateSafety(safetyQuery, { suggestions: false });
+          if (result.safety !== 0 /* Safe */ && result.safety >= minSeverity) {
+            result = evaluateSafety(safetyQuery, { partners: true });
+            const conflict = {
+              beat,
+              trackName: track.name,
+              trackIndex: track.trackIndex,
+              noteId: note.id,
+              pitch: note.pitch,
+              labels: labelsById.get(note.id) ?? [],
+              safety: result.safety,
+              reasons: result.reasons
+            };
+            if (note.originalIndex !== void 0) {
+              conflict.originalIndex = note.originalIndex;
+            }
+            if (result.rationale !== void 0) {
+              conflict.rationale = result.rationale;
+            }
+            if (result.resolveTo !== void 0) {
+              conflict.resolveTo = result.resolveTo;
+            }
+            if (result.suggestions !== void 0) {
+              conflict.suggestions = [...result.suggestions];
+            }
+            if (result.partners !== void 0) {
+              conflict.partners = result.partners.map(
+                ({ index, reasons }) => conflictPartner(others[index], reasons)
+              );
+            }
+            conflicts.push(conflict);
+          }
+        }
+      }
+    }
+    notes.sort((a, b) => a.noteId - b.noteId);
+    trackAnalyses.push({ name: track.name, role: track.role, notes });
+  }
+  conflicts.sort((a, b) => b.safety - a.safety || a.beat - b.beat);
+  const analysis = {
+    keys,
+    prevailingKey,
+    timeline,
+    segmentConfidence,
+    cadences,
+    tracks: trackAnalyses,
+    conflicts
+  };
+  return evidence === void 0 ? { analysis } : { analysis, evidence };
+}
+
+// src/analyze/arrange/session.ts
+function noteId(note) {
+  return `${note.pitch}|${note.startBeat}|${note.durationBeat}|${note.velocity ?? ""}`;
+}
+function sameOrder(before, after) {
+  if (before.length !== after.length) {
+    return false;
+  }
+  for (let index = 0; index < before.length; index += 1) {
+    const previous = before[index];
+    const current = after[index];
+    if (previous === void 0 || current === void 0 || noteId(previous) !== noteId(current)) {
+      return false;
+    }
+  }
+  return true;
+}
+function editedSpan(before, after) {
+  const counts = /* @__PURE__ */ new Map();
+  const tally = (notes, sign) => {
+    for (const note of notes) {
+      const id = noteId(note);
+      const entry = counts.get(id);
+      if (entry === void 0) {
+        counts.set(id, {
+          count: sign,
+          startBeat: note.startBeat,
+          endBeat: note.startBeat + note.durationBeat
+        });
+      } else {
+        entry.count += sign;
+      }
+    }
+  };
+  tally(before, 1);
+  tally(after, -1);
+  let startBeat = Number.POSITIVE_INFINITY;
+  let endBeat = Number.NEGATIVE_INFINITY;
+  for (const entry of counts.values()) {
+    if (entry.count === 0) {
+      continue;
+    }
+    startBeat = Math.min(startBeat, entry.startBeat);
+    endBeat = Math.max(endBeat, entry.endBeat, entry.startBeat);
+  }
+  return startBeat <= endBeat ? { startBeat, endBeat } : null;
+}
+function unionSpan(a, b) {
+  if (a === null) {
+    return b;
+  }
+  if (b === null) {
+    return a;
+  }
+  return {
+    startBeat: Math.min(a.startBeat, b.startBeat),
+    endBeat: Math.max(a.endBeat, b.endBeat)
+  };
+}
+function sessionOf(tracks, opts, analysis, evidence) {
+  return {
+    tracks,
+    analysis,
+    update(edits) {
+      assertGenerationBudget(edits.length, "arrangement edits", opts.budget);
+      const next = [...tracks];
+      let edited = null;
+      let reordered = false;
+      for (let index = 0; index < edits.length; index += 1) {
+        const edit = edits[index];
+        if (edit === void 0) {
+          continue;
+        }
+        const target = next[edit.trackIndex];
+        if (target === void 0) {
+          throw new InvalidInputError(
+            `edits[${index}].trackIndex ${edit.trackIndex} is outside the session's ${tracks.length} tracks`
+          );
+        }
+        if (!Array.isArray(edit.notes)) {
+          throw new InvalidInputError(
+            `edits[${index}].notes must be an array; received ${typeof edit.notes}`
+          );
+        }
+        assertNoteEvents(edit.notes, `edits[${index}].notes`, {
+          allowNonPositiveDuration: true,
+          budget: opts.budget
+        });
+        edited = unionSpan(edited, editedSpan(target.notes, edit.notes));
+        reordered = reordered || !sameOrder(target.notes, edit.notes);
+        next[edit.trackIndex] = { ...target, notes: edit.notes };
+      }
+      if (edited === null && !reordered) {
+        return sessionOf(next, opts, analysis, evidence);
+      }
+      const dirty = evidence === void 0 ? void 0 : edited === null ? { from: 0, to: 0 } : dirtySlotsFor(evidence, edited.startBeat, edited.endBeat);
+      const run = analyzeArrangementWith(next, opts, evidence, dirty);
+      return sessionOf(next, opts, run.analysis, run.evidence);
+    }
+  };
+}
+function createArrangementSession(tracks, opts = {}) {
+  const run = analyzeArrangementWith(tracks, opts);
+  return sessionOf([...tracks], opts, run.analysis, run.evidence);
+}
+
+// src/analyze/arrange/tension.ts
+var FUNCTION_TENSION = {
+  tonic: 0,
+  subdominant: 0.5,
+  dominant: 1
+};
+var FUNCTION_WEIGHT = 0.5;
+var DISSONANCE_WEIGHT = 0.35;
+var SPAN_WEIGHT = 0.15;
+var SPAN_SATURATION = 24;
+function clamp012(value) {
+  return Math.min(1, Math.max(0, value));
+}
+function tensionCurve(tracks, opts = {}) {
+  const meters = resolveMeters(opts, "arrangement meters");
+  const budget = opts.budget;
+  const noteOptions = { allowNonPositiveDuration: true, budget };
+  if (opts.pickupBeats !== void 0) {
+    assertRange(opts.pickupBeats, 0, Number.MAX_SAFE_INTEGER, "arrangement pickupBeats");
+    noteOptions.minStartBeat = -opts.pickupBeats;
+  }
+  assertArray(tracks, "arrangement tracks");
+  assertGenerationBudget(tracks.length, "arrangement tracks", budget);
+  const noteCount = assertTrackNotes(tracks, noteOptions);
+  assertGenerationBudget(noteCount, "arrangement notes", budget);
+  const profile = arrangementProfile(opts.profile);
+  const step = opts.step ?? 1;
+  assertRange(step, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "tension sampling step");
+  if (opts.minSeverity !== void 0) {
+    assertInteger(
+      opts.minSeverity,
+      "arrangement minSeverity",
+      0 /* Safe */,
+      2 /* Dissonant */
+    );
+  }
+  assertGivenTimeline(opts.timeline, "arrangement timeline");
+  assertGivenKeys(opts.keys, "arrangement keys");
+  const harmonyTracks = harmonyTrackSet(opts.harmonyTracks, tracks);
+  const pooled = poolNotes(tracks, harmonyTracks);
+  const all = poolNotes(tracks);
+  const totalBeats = all.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  const { origin: sampleStart, startBeat: musicStart } = gridForNotes(all, step);
+  const suppliedKeys = opts.timeline === void 0 ? void 0 : opts.keys ?? (opts.key !== void 0 ? [
+    {
+      // The one region a named key holds starts where the music does,
+      // as the searched regions and the timeline's own key window do:
+      // a key cannot be in force over beats nothing sounds in.
+      startBeat: musicStart,
+      endBeat: totalBeats,
+      key: resolveKey(opts.key),
+      confidence: 1
+    }
+  ] : keyTimelineFromNotes(pooled, { meters, totalBeats, budget }));
+  const { timeline, keys, prevailingKey } = opts.timeline === void 0 || suppliedKeys === void 0 ? chordTimelineFromNotes(pooled, {
+    key: opts.key,
+    meters,
+    pickupBeats: opts.pickupBeats,
+    harmonicRhythm: opts.harmonicRhythm,
+    budget
+  }) : {
+    timeline: opts.timeline,
+    keys: suppliedKeys,
+    prevailingKey: prevailingKeyOf(suppliedKeys) ?? resolveKey(majorKey(0))
+  };
+  const regions = opts.keys ?? keys;
+  const keyAt = keyLookup(regions, prevailingKeyOf(regions) ?? prevailingKey);
+  const prepared = prepareTracks(tracks);
+  const points = [];
+  const sampleCount = Math.max(0, Math.ceil((totalBeats - sampleStart) / step - BEAT_EPS));
+  assertGenerationBudget(sampleCount, "tension samples", budget);
+  const voiceCount = prepared.reduce((sum, track) => sum + track.voices.length, 0);
+  assertGenerationBudget(
+    sampleCount * Math.min(128, voiceCount) * voiceCount,
+    "tension sample-voice comparisons",
+    budget
+  );
+  for (let i = 0; i < sampleCount; i += 1) {
+    const beat = i === 0 ? Math.max(sampleStart, musicStart) : sampleStart + i * step;
+    points.push({
+      beat,
+      // The pitch classes alone: tension is scored from what sounds against
+      // the tonic, and no reading below here asks how the key is written.
+      tension: sampleTension(prepared, timeline, scaleOf(keyAt(beat)), meters, profile, beat)
+    });
+  }
+  return points;
+}
+function tensionCurveFrom(tracks, analysis, opts = {}) {
+  const asked = assertRecord(opts, "opts");
+  const carried = carriedHarmony(assertRecord(analysis, "analysis"), asked);
+  return tensionCurve(tracks, { ...carried, ...asked });
+}
+function carriedHarmony(analysis, opts) {
+  if (opts.harmonyTracks !== void 0) {
+    return {};
+  }
+  if (opts.key !== void 0 || opts.keys !== void 0) {
+    return { timeline: analysis.timeline };
+  }
+  return { timeline: analysis.timeline, keys: analysis.keys };
+}
+function allSounding(prepared, beat) {
+  const out = [];
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track || isPercussion(track.role)) {
+      continue;
+    }
+    for (const subVoice of track.voices) {
+      const note = subVoice.at(beat);
+      if (note !== void 0) {
+        out.push({ pitch: note.pitch, track: t });
+      }
+    }
+  }
+  return out;
+}
+function sampleTension(prepared, timeline, key, meters, profile, beat) {
+  const sounding = allSounding(prepared, beat);
+  if (sounding.length === 0) {
+    return 0;
+  }
+  const chord = timeline.at(beat);
+  const functionScore = chord ? FUNCTION_TENSION[functionOf(chord, key)] : 0;
+  const chordPcs = chord ? new Set(chordPitchClasses(chord)) : null;
+  const strongBeat = isStrongBeat(beat, meters);
+  let nonChord = 0;
+  let dissonant = 0;
+  const pitches = /* @__PURE__ */ new Map();
+  for (const voice of sounding) {
+    pitches.set(voice.pitch, (pitches.get(voice.pitch) ?? 0) + 1);
+  }
+  const others = [];
+  const firstOf = /* @__PURE__ */ new Map();
+  for (const [pitch, count] of pitches) {
+    firstOf.set(pitch, others.length);
+    for (let i = 0; i < count; i += 1) {
+      others.push({ pitch });
+    }
+  }
+  for (const [pitch, count] of pitches) {
+    if (chordPcs && !chordPcs.has(pitchClassOf(pitch))) {
+      nonChord += count;
+    }
+    const at = firstOf.get(pitch) ?? 0;
+    const last = others.length - 1;
+    const held = others[at];
+    const tail = others[last];
+    if (held !== void 0 && tail !== void 0) {
+      others[at] = tail;
+      others.pop();
+    }
+    const result = evaluateSafety(
+      { profile, candidatePitch: pitch, chord, key, otherVoices: others, strongBeat },
+      { suggestions: false }
+    );
+    if (held !== void 0 && tail !== void 0) {
+      others.push(tail);
+      others[at] = held;
+    }
+    if (result.safety === 2 /* Dissonant */) {
+      dissonant += count;
+    }
+  }
+  const dissonanceScore = Math.max(nonChord, dissonant) / sounding.length;
+  let low = Number.POSITIVE_INFINITY;
+  let high = Number.NEGATIVE_INFINITY;
+  for (const voice of sounding) {
+    low = Math.min(low, voice.pitch);
+    high = Math.max(high, voice.pitch);
+  }
+  const spanScore = Math.min(1, (high - low) / SPAN_SATURATION);
+  return clamp012(
+    FUNCTION_WEIGHT * functionScore + DISSONANCE_WEIGHT * dissonanceScore + SPAN_WEIGHT * spanScore
+  );
+}
+
+// src/analyze/form/hypermeter.ts
+var GROUP_CANDIDATES = [2, 3, 4, 6, 8];
+var GROUP_PRIOR = /* @__PURE__ */ new Map([
+  [2, 0.9],
+  [3, 0.75],
+  [4, 1],
+  [6, 0.7],
+  [8, 0.85]
+]);
+var CONTRAST_SHARE = 0.65;
+var CADENCE_SHARE = 0.35;
+var GROUP_FINAL_FIT = 1;
+var ELIDED_FIT = 0.5;
+var MIN_GROUPS = 2;
+var MARGIN_FLOOR = 0.7;
+function accentContrast(novelty, slices, groupBars, phase) {
+  let headSum = 0;
+  let headCount = 0;
+  let otherSum = 0;
+  let otherCount = 0;
+  for (let i = 0; i < slices.length; i += 1) {
+    const slice = slices[i];
+    if (slice === void 0) {
+      continue;
+    }
+    const value = novelty[i] ?? 0;
+    if (floorMod(slice.index - phase, groupBars) === 0) {
+      headSum += value;
+      headCount += 1;
+    } else {
+      otherSum += value;
+      otherCount += 1;
+    }
+  }
+  if (headCount === 0 || otherCount === 0) {
+    return 0;
+  }
+  return headSum / headCount - otherSum / otherCount;
+}
+function cadenceFitOf(cadenceBars, slices, groupBars, phase) {
+  const lastBar = slices[slices.length - 1]?.index ?? -1;
+  let ends = 0;
+  let fit = 0;
+  for (const slice of slices) {
+    if (slice.index < 0 || floorMod(slice.index - phase, groupBars) !== groupBars - 1) {
+      continue;
+    }
+    ends += 1;
+    if (cadenceBars.has(slice.index)) {
+      fit += GROUP_FINAL_FIT;
+    } else if (slice.index < lastBar && cadenceBars.has(slice.index + 1)) {
+      fit += ELIDED_FIT;
+    }
+  }
+  return ends === 0 ? 0 : clamp01(fit / ends);
+}
+function undecidedReading(slices) {
+  const fullBars = slices.filter((slice) => slice.index >= 0);
+  const groupBars = Math.max(1, fullBars.length);
+  const first = fullBars[0];
+  return {
+    groupBars,
+    downbeats: first === void 0 ? [] : [first.startBeat],
+    confidence: 0,
+    rationale: `Span of ${fullBars.length} bar(s) is too short to establish a grouping; read as one group`
+  };
+}
+function hypermeter(notes, meter, opts = {}) {
+  const asked = assertOptions(opts, "opts");
+  const meters = resolveMeters({ meters: meter }, "meter");
+  assertNoteEvents(notes, "hypermeter notes", {
+    allowNonPositiveDuration: true,
+    budget: asked.budget
+  });
+  const sounding = notes.filter((note) => note.durationBeat > 0);
+  const firstOnset = firstSoundingBeat(sounding);
+  const lastEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  const spanEnd = asked.totalBeats ?? lastEnd;
+  assertRange(spanEnd, 0, Number.MAX_SAFE_INTEGER, "hypermeter totalBeats");
+  const spanStart = barGridStart(firstOnset, meters);
+  const slices = sliceBars(sounding, meters, spanStart, spanEnd, asked.budget);
+  const fullBars = slices.reduce((count, slice) => slice.index >= 0 ? count + 1 : count, 0);
+  const candidates = GROUP_CANDIDATES.filter((groupBars) => fullBars >= groupBars * MIN_GROUPS);
+  if (candidates.length === 0) {
+    return undecidedReading(slices);
+  }
+  assertGenerationBudget(
+    candidates.reduce((sum, groupBars) => sum + groupBars * slices.length, 0),
+    "hypermeter readings",
+    asked.budget
+  );
+  const novelty = slices.map((_, index) => harmonicNovelty(slices, index));
+  const cadenceBars = new Set((asked.cadenceBeats ?? []).map((beat) => barIndexAt(beat, meters)));
+  const hasCadences = cadenceBars.size > 0;
+  const readings = [];
+  for (const groupBars of candidates) {
+    const phases = Array.from({ length: groupBars }, (_, phase) => ({
+      phase,
+      contrast: accentContrast(novelty, slices, groupBars, phase),
+      cadenceFit: cadenceFitOf(cadenceBars, slices, groupBars, phase)
+    }));
+    const bestFit = phases.reduce((best2, reading) => Math.max(best2, reading.cadenceFit), 0);
+    for (const { phase, contrast, cadenceFit } of phases) {
+      if (hasCadences && cadenceFit < bestFit - BEAT_EPS) {
+        continue;
+      }
+      const evidence = clamp01(
+        hasCadences ? (
+          // Floored at zero rather than summed raw: group heads that restate
+          // the harmony their group opened with — the commonest way a phrase
+          // begins — change less than the bars between them, and a negative
+          // contrast subtracted from the cadence term would count that
+          // restatement as evidence against the very phase it confirms.
+          CONTRAST_SHARE * clamp01(contrast) + CADENCE_SHARE * cadenceFit
+        ) : contrast
+      );
+      readings.push({
+        groupBars,
+        phase,
+        contrast,
+        cadenceFit,
+        evidence,
+        score: evidence * (GROUP_PRIOR.get(groupBars) ?? 0)
+      });
+    }
+  }
+  readings.sort(
+    (a, b) => b.score - a.score || (GROUP_PRIOR.get(b.groupBars) ?? 0) - (GROUP_PRIOR.get(a.groupBars) ?? 0) || a.groupBars - b.groupBars || a.phase - b.phase
+  );
+  const best = readings[0];
+  if (best === void 0) {
+    return undecidedReading(slices);
+  }
+  const runnerUp = readings.find((reading) => reading.groupBars !== best.groupBars);
+  const margin = runnerUp === void 0 || best.score <= BEAT_EPS ? 1 : clamp01((best.score - runnerUp.score) / best.score);
+  const downbeats = slices.filter((slice) => slice.index >= 0 && floorMod(slice.index - best.phase, best.groupBars) === 0).map((slice) => slice.startBeat);
+  const cadencePart = hasCadences ? `${Math.round(best.cadenceFit * 100)}% of group ends closed by a cadence` : "no cadences given";
+  return {
+    groupBars: best.groupBars,
+    downbeats,
+    // Mostly the evidence, discounted when a rival grouping explains the
+    // accents nearly as well. The discount is the smaller term because the
+    // runner-up is nearly always a multiple or a divisor of the winner — four
+    // bars nest inside eight — and a reading of the same accents at another
+    // level is weaker counter-evidence than an unrelated rival would be.
+    confidence: clamp01(best.evidence * (MARGIN_FLOOR + (1 - MARGIN_FLOOR) * margin)),
+    rationale: `${best.groupBars}-bar groups from bar ${best.phase}: harmonic change ${Math.round(best.contrast * 100)}% stronger on group heads, ${cadencePart}`
+  };
+}
+
+// src/analyze/melody/internal.ts
+var RHYTHM_GRID = 64;
+function phraseNotes(phrase) {
+  if (Array.isArray(phrase)) {
+    return phrase;
+  }
+  return assertRecord(phrase, "melodic phrase").notes;
+}
+function orderedNotes(notes, name, budget) {
+  assertNoteEvents(notes, name, { allowNonPositiveDuration: true, budget });
+  const sounding = notes.filter((note) => note.durationBeat > 0).sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
+  const line = [];
+  for (const note of sounding) {
+    const previous = line[line.length - 1];
+    if (previous !== void 0 && Math.abs(note.startBeat - previous.startBeat) <= BEAT_EPS) {
+      line[line.length - 1] = note;
+      continue;
+    }
+    line.push(note);
+  }
+  return line;
+}
+function intervalsOf(notes) {
+  const out = [];
+  for (let i = 1; i < notes.length; i += 1) {
+    out.push((notes[i]?.pitch ?? 0) - (notes[i - 1]?.pitch ?? 0));
+  }
+  return out;
+}
+function onsetGaps(notes) {
+  const out = [];
+  for (let i = 1; i < notes.length; i += 1) {
+    out.push((notes[i]?.startBeat ?? 0) - (notes[i - 1]?.startBeat ?? 0));
+  }
+  return out;
+}
+function retrogradeGaps(notes) {
+  const out = [];
+  for (let i = notes.length - 1; i >= 1; i -= 1) {
+    const later = notes[i];
+    const earlier = notes[i - 1];
+    out.push(
+      (later?.startBeat ?? 0) + (later?.durationBeat ?? 0) - ((earlier?.startBeat ?? 0) + (earlier?.durationBeat ?? 0))
+    );
+  }
+  return out;
+}
+function rhythmProfile(gaps) {
+  const unit = gaps[0] ?? 0;
+  if (!(unit > BEAT_EPS)) {
+    return gaps.length === 0 ? [] : null;
+  }
+  return gaps.map((gap) => Math.round(gap / unit * RHYTHM_GRID) / RHYTHM_GRID);
+}
+function sameNumbers(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i += 1) {
+    if (Math.abs((a[i] ?? 0) - (b[i] ?? 0)) > BEAT_EPS) {
+      return false;
+    }
+  }
+  return true;
+}
+function roundTo(value, digits) {
+  const scale = 10 ** digits;
+  return Math.round(value * scale) / scale;
+}
+function endBeatOf(notes) {
+  let end = 0;
+  for (const note of notes) {
+    end = Math.max(end, note.startBeat + note.durationBeat);
+  }
+  return end;
+}
+function onsetSpan(notes) {
+  if (notes.length < 2) {
+    return 0;
+  }
+  return (notes[notes.length - 1]?.startBeat ?? 0) - (notes[0]?.startBeat ?? 0);
+}
+
+// src/analyze/melody/contour.ts
+var DIRECTIONAL_SHARE = 0.75;
+function extremes(notes) {
+  if (notes.length === 0) {
+    return { peak: -1, trough: -1 };
+  }
+  let peak = 0;
+  let trough = 0;
+  for (let i = 1; i < notes.length; i += 1) {
+    if ((notes[i]?.pitch ?? 0) > (notes[peak]?.pitch ?? 0)) {
+      peak = i;
+    }
+    if ((notes[i]?.pitch ?? 0) < (notes[trough]?.pitch ?? 0)) {
+      trough = i;
+    }
+  }
+  return { peak, trough };
+}
+function melodicContour(notes) {
+  const line = orderedNotes(phraseNotes(notes), "contour notes");
+  const intervals = intervalsOf(line);
+  const directions = intervals.map(
+    (step) => step > 0 ? "up" : step < 0 ? "down" : "same"
+  );
+  const { peak, trough } = extremes(line);
+  const range = (line[peak]?.pitch ?? 0) - (line[trough]?.pitch ?? 0);
+  const motion = intervals.reduce((sum, step) => sum + Math.abs(step), 0);
+  if (motion === 0) {
+    return {
+      directions,
+      shape: "static",
+      peakIndex: peak,
+      troughIndex: trough,
+      range: 0,
+      rationale: line.length < 2 ? "Too short to have a direction, so the line is static" : "Every note at the same pitch, so the line is static"
+    };
+  }
+  const first = line[0]?.pitch ?? 0;
+  const last = line[line.length - 1]?.pitch ?? 0;
+  const net = last - first;
+  const directness = Math.abs(net) / motion;
+  const share = Math.round(directness * 100);
+  if (directness >= DIRECTIONAL_SHARE) {
+    const shape = net > 0 ? "ascending" : "descending";
+    return {
+      directions,
+      shape,
+      peakIndex: peak,
+      troughIndex: trough,
+      range,
+      rationale: `${share}% of the motion runs ${net > 0 ? "up" : "down"}, so the line is ${shape}`
+    };
+  }
+  const peakPitch = line[peak]?.pitch ?? 0;
+  const archMotion = peakPitch - first + (peakPitch - last);
+  if (peak > 0 && peak < line.length - 1 && archMotion >= DIRECTIONAL_SHARE * motion) {
+    return {
+      directions,
+      shape: "arch",
+      peakIndex: peak,
+      troughIndex: trough,
+      range,
+      rationale: `Rises to its peak at note ${peak + 1} of ${line.length} and falls back, so the line is an arch`
+    };
+  }
+  return {
+    directions,
+    shape: "wave",
+    peakIndex: peak,
+    troughIndex: trough,
+    range,
+    rationale: `Changes direction without settling either way (${share}% of the motion nets out), so the line is a wave`
+  };
+}
+
+// src/analyze/melody/motifs.ts
+var MIN_CELL_NOTES = 3;
+var MAX_CELL_NOTES = 8;
+var MIN_OCCURRENCES = 2;
+function windowSignature(notes) {
+  const profile = rhythmProfile(onsetGaps(notes));
+  if (profile === null) {
+    return null;
+  }
+  return `${notes.length}|${intervalsOf(notes).join(",")}|${profile.join(",")}`;
+}
+function nonOverlapping(starts, length) {
+  const picked = [];
+  let lastEnd = Number.NEGATIVE_INFINITY;
+  for (const start of starts) {
+    if (start > lastEnd) {
+      picked.push(start);
+      lastEnd = start + length - 1;
+    }
+  }
+  return picked;
+}
+function subsumes(outer, inner) {
+  let at = 0;
+  for (const start of inner.starts) {
+    while (at + 1 < outer.starts.length && (outer.starts[at + 1] ?? 0) <= start) {
+      at += 1;
+    }
+    const from = outer.starts[at];
+    if (from === void 0 || start < from || start + inner.length > from + outer.length) {
+      return false;
+    }
+  }
+  return true;
+}
+function listBeats(occurrences) {
+  const shown = occurrences.slice(0, 5).map((occurrence) => roundTo(occurrence.startBeat, 3));
+  return occurrences.length > shown.length ? `${shown.join(", ")}, and ${occurrences.length - shown.length} more` : shown.join(", ");
+}
+function motifFromGroup(group, notes) {
+  const first = group.starts[0] ?? 0;
+  const prime = notes.slice(first, first + group.length).map((note) => ({ ...note }));
+  const primePitch = prime[0]?.pitch ?? 0;
+  const primeSpan = onsetSpan(prime);
+  const occurrences = group.starts.map((start) => {
+    const statement = notes.slice(start, start + group.length);
+    const span = onsetSpan(statement);
+    return {
+      noteIndex: start,
+      startBeat: statement[0]?.startBeat ?? 0,
+      endBeat: endBeatOf(statement),
+      transpose: (statement[0]?.pitch ?? 0) - primePitch,
+      timeRatio: primeSpan > BEAT_EPS ? span / primeSpan : 1
+    };
+  });
+  const shape = melodicContour(prime).shape;
+  const transposed = occurrences.some((occurrence) => occurrence.transpose !== 0);
+  const stretched = occurrences.some((occurrence) => Math.abs(occurrence.timeRatio - 1) > BEAT_EPS);
+  const detail = [
+    transposed ? "at more than one pitch level" : "at the same pitch level",
+    stretched ? "and in more than one set of note values" : ""
+  ].filter((part) => part !== "").join(" ");
+  return {
+    notes: prime,
+    intervals: intervalsOf(prime),
+    rhythm: rhythmProfile(onsetGaps(prime)) ?? [],
+    occurrences,
+    rationale: `${group.length}-note ${shape} cell stated ${occurrences.length} ${occurrences.length === 1 ? "time" : "times"} (beats ${listBeats(occurrences)}), ${detail}`
+  };
+}
+function extractMotifs(notes, opts = {}) {
+  const asked = assertOptions(opts, "opts");
+  const minNotes = assertInteger(asked.minNotes ?? MIN_CELL_NOTES, "motif minNotes", 2, 64);
+  const maxNotes = assertInteger(asked.maxNotes ?? MAX_CELL_NOTES, "motif maxNotes", 2, 64);
+  if (maxNotes < minNotes) {
+    throw new InvalidInputError(
+      `motif maxNotes must be at least minNotes ${minNotes}; received ${maxNotes}`
+    );
+  }
+  const minOccurrences = assertInteger(
+    asked.minOccurrences ?? MIN_OCCURRENCES,
+    "motif minOccurrences",
+    2
+  );
+  const sounding = orderedNotes(notes, "melody notes", asked.budget);
+  if (sounding.length < minNotes) {
+    return [];
+  }
+  assertGenerationBudget(
+    sounding.length * (maxNotes - minNotes + 1),
+    "motif windows",
+    asked.budget
+  );
+  const groups = /* @__PURE__ */ new Map();
+  for (let length = minNotes; length <= maxNotes; length += 1) {
+    for (let start = 0; start + length <= sounding.length; start += 1) {
+      const signature = windowSignature(sounding.slice(start, start + length));
+      if (signature === null) {
+        continue;
+      }
+      const group = groups.get(signature);
+      if (group === void 0) {
+        groups.set(signature, { signature, length, starts: [start] });
+      } else {
+        group.starts.push(start);
+      }
+    }
+  }
+  const candidates = [...groups.values()].map((group) => ({ ...group, starts: nonOverlapping(group.starts, group.length) })).filter((group) => group.starts.length >= minOccurrences).sort(
+    (a, b) => b.length - a.length || b.starts.length - a.starts.length || (a.starts[0] ?? 0) - (b.starts[0] ?? 0) || (a.signature < b.signature ? -1 : a.signature > b.signature ? 1 : 0)
+  );
+  const keptByLength = /* @__PURE__ */ new Map();
+  const kept = [];
+  let comparisons = 0;
+  for (const candidate of candidates) {
+    const first = candidate.starts[0] ?? 0;
+    let covered = false;
+    for (let length = candidate.length + 1; length <= maxNotes && !covered; length += 1) {
+      const byStart = keptByLength.get(length);
+      if (byStart === void 0) {
+        continue;
+      }
+      for (let from = Math.max(0, first - (length - candidate.length)); from <= first; from += 1) {
+        comparisons += 1;
+        const outer = byStart.get(from);
+        if (outer === void 0 || outer.starts.length < candidate.starts.length) {
+          continue;
+        }
+        comparisons += outer.starts.length + candidate.starts.length;
+        if (subsumes(outer, candidate)) {
+          covered = true;
+          break;
+        }
+      }
+    }
+    assertGenerationBudget(comparisons, "motif subsumption comparisons", asked.budget);
+    if (!covered) {
+      kept.push(candidate);
+      let byStart = keptByLength.get(candidate.length);
+      if (byStart === void 0) {
+        byStart = /* @__PURE__ */ new Map();
+        keptByLength.set(candidate.length, byStart);
+      }
+      for (const start of candidate.starts) {
+        byStart.set(start, candidate);
+      }
+    }
+  }
+  return kept.map((group) => motifFromGroup(group, sounding));
+}
+function motifFromNotes(notes) {
+  const sounding = orderedNotes(notes, "motif notes").map((note) => ({ ...note }));
+  return motifFromGroup(
+    { signature: windowSignature(sounding) ?? "", length: sounding.length, starts: [0] },
+    sounding
+  );
+}
+
+// src/analyze/melody/relation.ts
+function spellingOf(key) {
+  if (key === void 0) {
+    return "sharp";
+  }
+  return keySignatureFifths(key.tonic, key.scale) < 0 ? "flat" : "sharp";
+}
+function intervalBetween(from, to, key) {
+  const spelling = spellingOf(key);
+  return spelledInterval(midiToNote(from, spelling), midiToNote(to, spelling));
+}
+function intervalName(interval) {
+  return `${interval.descending && interval.semitones !== 0 ? "-" : ""}${interval.quality}${interval.number}`;
+}
+function ladderIndices(notes, key) {
+  const root = pitchClassOf(key.rootPc);
+  const offsets = scaleTonesInDegreeOrder(key).map((pc) => pitchClassOf(pc - root));
+  if (offsets.length === 0) {
+    return null;
+  }
+  const out = [];
+  for (const note of notes) {
+    const semitones = note.pitch - root;
+    const octave = Math.floor(semitones / 12);
+    const degree = offsets.indexOf(semitones - octave * 12);
+    if (degree < 0) {
+      return null;
+    }
+    out.push(octave * offsets.length + degree);
+  }
+  return out;
+}
+function ladderSteps(indices) {
+  const out = [];
+  for (let i = 1; i < indices.length; i += 1) {
+    out.push((indices[i] ?? 0) - (indices[i - 1] ?? 0));
+  }
+  return out;
+}
+function pitchShapes(a, b) {
+  const shapes = [];
+  if (sameNumbers(a, b)) {
+    shapes.push("exact");
+  }
+  if (sameNumbers(
+    b,
+    a.map((step) => -step)
+  )) {
+    shapes.push("inversion");
+  }
+  const reversed = [...a].reverse();
+  if (sameNumbers(
+    b,
+    reversed.map((step) => -step)
+  )) {
+    shapes.push("retrograde");
+  }
+  if (sameNumbers(b, reversed)) {
+    shapes.push("retrogradeInversion");
+  }
+  return shapes;
+}
+function totalGap(gaps) {
+  return gaps.reduce((sum, gap) => sum + gap, 0);
+}
+function stretchRatio(modelGaps, answerGaps) {
+  const span = totalGap(modelGaps);
+  return span > BEAT_EPS ? totalGap(answerGaps) / span : 1;
+}
+function stretchPhrase(ratio) {
+  return `note values ${roundTo(ratio, 3)}x the model's`;
+}
+function relateMotifs(a, b, keyLike) {
+  const key = keyLike === void 0 ? void 0 : resolveKey(keyLike);
+  const model = assertArray(assertRecord(a, "a").notes, "a.notes");
+  const answer = assertArray(assertRecord(b, "b").notes, "b.notes");
+  if (model.length === 0 || model.length !== answer.length) {
+    return null;
+  }
+  const modelGaps = onsetGaps(model);
+  const answerGaps = onsetGaps(answer);
+  const modelProfile = rhythmProfile(modelGaps);
+  const answerProfile = rhythmProfile(answerGaps);
+  const retroGaps = retrogradeGaps(model);
+  const retroProfile = rhythmProfile(retroGaps);
+  if (modelProfile === null || answerProfile === null) {
+    return null;
+  }
+  const forward = sameNumbers(modelProfile, answerProfile);
+  const backward = retroProfile !== null && sameNumbers(retroProfile, answerProfile);
+  const semitones = (answer[0]?.pitch ?? 0) - (model[0]?.pitch ?? 0);
+  const interval = intervalBetween(model[0]?.pitch ?? 0, answer[0]?.pitch ?? 0, key);
+  const gap = (answer[0]?.startBeat ?? 0) - endBeatOf(model);
+  const sequence = gap >= -HUMANIZE_ADJACENCY && gap <= HUMANIZE_ADJACENCY;
+  const timeRatio = stretchRatio(modelGaps, answerGaps);
+  const stretched = Math.abs(timeRatio - 1) > BEAT_EPS;
+  const shapes = pitchShapes(intervalsOf(model), intervalsOf(answer));
+  const base = { sequence, semitones, interval, timeRatio };
+  const backwardBase = { ...base, timeRatio: stretchRatio(retroGaps, answerGaps) };
+  if (forward && shapes.includes("exact")) {
+    if (semitones === 0) {
+      if (!stretched) {
+        return {
+          ...base,
+          kind: "repetition",
+          rationale: "Exact repetition: the same pitches in the same rhythm"
+        };
+      }
+      const augmented = timeRatio > 1;
+      return {
+        ...base,
+        kind: augmented ? "augmentation" : "diminution",
+        rationale: `${augmented ? "Augmentation" : "Diminution"}: the same pitches in ${stretchPhrase(timeRatio)}`
+      };
+    }
+    const name = intervalName(interval);
+    return {
+      ...base,
+      kind: "transposition",
+      rationale: sequence ? `Real sequence: the cell restated ${name} away with every interval kept literally` + (stretched ? `, in ${stretchPhrase(timeRatio)}` : "") : `Transposition by ${name}: every interval kept literally` + (stretched ? `, in ${stretchPhrase(timeRatio)}` : "")
+    };
+  }
+  if (forward && key !== void 0) {
+    const modelLadder = ladderIndices(model, key.scale);
+    const answerLadder = ladderIndices(answer, key.scale);
+    if (modelLadder !== null && answerLadder !== null) {
+      const degrees = (answerLadder[0] ?? 0) - (modelLadder[0] ?? 0);
+      if (degrees !== 0 && sameNumbers(ladderSteps(modelLadder), ladderSteps(answerLadder))) {
+        const direction = degrees > 0 ? "higher" : "lower";
+        const count = Math.abs(degrees);
+        return {
+          ...base,
+          kind: "tonalTransposition",
+          degrees,
+          rationale: `${sequence ? "Tonal sequence" : "Tonal transposition"}: the cell restated ${count} scale ${count === 1 ? "degree" : "degrees"} ${direction} inside the key, so the key resizes its intervals \u2014 a real one would have kept them literal`
+        };
+      }
+    }
+  }
+  if (forward && shapes.includes("inversion")) {
+    return {
+      ...base,
+      kind: "inversion",
+      rationale: "Inversion: every interval turned upside down about the first note" + (stretched ? `, in ${stretchPhrase(timeRatio)}` : "")
+    };
+  }
+  if (backward && shapes.includes("retrograde")) {
+    return {
+      ...backwardBase,
+      kind: "retrograde",
+      rationale: "Retrograde: the cell read back to front, rhythm included"
+    };
+  }
+  if (backward && shapes.includes("retrogradeInversion")) {
+    return {
+      ...backwardBase,
+      kind: "retrogradeInversion",
+      rationale: "Retrograde inversion: the cell read back to front and turned upside down"
+    };
+  }
+  return null;
+}
+
+// src/analyze/melody/similarity.ts
+var INTERVAL_TOLERANCE = 6;
+var PITCH_WEIGHT = 0.75;
+var RHYTHM_WEIGHT = 0.25;
+function gradedEditDistance(a, b, cost) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    const row = new Array(b.length + 1);
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const substitution = (previous[j - 1] ?? 0) + cost(a[i - 1] ?? 0, b[j - 1] ?? 0);
+      const deletion = (previous[j] ?? 0) + 1;
+      const insertion = (row[j - 1] ?? 0) + 1;
+      row[j] = Math.min(substitution, deletion, insertion);
+    }
+    previous = row;
+  }
+  return previous[b.length] ?? 0;
+}
+function distanceToSimilarity(distance, a, b) {
+  const longest = Math.max(a, b);
+  if (longest === 0) {
+    return 1;
+  }
+  return Math.min(1, Math.max(0, 1 - distance / longest));
+}
+function intervalCost(x, y) {
+  return Math.min(1, Math.abs(x - y) / INTERVAL_TOLERANCE);
+}
+function gapCost(x, y) {
+  if (!(x > BEAT_EPS) || !(y > BEAT_EPS)) {
+    return Math.abs(x - y) > BEAT_EPS ? 1 : 0;
+  }
+  return Math.min(1, Math.abs(Math.log2(x / y)));
+}
+function compareMelodies(a, b) {
+  const left = orderedNotes(phraseNotes(a), "melody a");
+  const right = orderedNotes(phraseNotes(b), "melody b");
+  const leftIntervals = intervalsOf(left);
+  const rightIntervals = intervalsOf(right);
+  const pitchSimilarity = distanceToSimilarity(
+    gradedEditDistance(leftIntervals, rightIntervals, intervalCost),
+    leftIntervals.length,
+    rightIntervals.length
+  );
+  const leftGaps = rhythmProfile(onsetGaps(left)) ?? onsetGaps(left);
+  const rightGaps = rhythmProfile(onsetGaps(right)) ?? onsetGaps(right);
+  const rhythmSimilarity = distanceToSimilarity(
+    gradedEditDistance(leftGaps, rightGaps, gapCost),
+    leftGaps.length,
+    rightGaps.length
+  );
+  const similarity = PITCH_WEIGHT * pitchSimilarity + RHYTHM_WEIGHT * rhythmSimilarity;
+  return {
+    similarity,
+    pitchSimilarity,
+    rhythmSimilarity,
+    rationale: `Interval shapes ${Math.round(pitchSimilarity * 100)}% alike, rhythms ${Math.round(rhythmSimilarity * 100)}% alike, weighted ${PITCH_WEIGHT}/${RHYTHM_WEIGHT} into ${roundTo(similarity, 3)}`
+  };
+}
+function melodicSimilarity(a, b) {
+  return compareMelodies(a, b).similarity;
+}
+
+// src/analyze/form/phrase.ts
+var CADENCE_BOUNDARY_STRENGTH = {
+  authentic: 0.9,
+  modal: 0.75,
+  plagal: 0.7,
+  phrygian: 0.65,
+  half: 0.6,
+  deceptive: 0.45
+};
+var CADENCE_CLOSURE = {
+  authentic: 0.85,
+  modal: 0.6,
+  plagal: 0.55,
+  phrygian: 0.4,
+  half: 0.35,
+  deceptive: 0.3
+};
+var REST_STRENGTH = 0.6;
+var LONG_NOTE_STRENGTH = 0.4;
+var REPETITION_STRENGTH = 0.5;
+var REPETITION_THRESHOLD = 0.75;
+var HYPERMETER_STRENGTH = 0.25;
+var PIECE_END_STRENGTH = 0.5;
+var PHRASE_CUT_COST = 1.3;
+var CLOSING_SHARE = 0.65;
+var FINAL_PHRASE_BONUS = 0.15;
+var HYPERMETRIC_CLOSE_BONUS = 0.1;
+var EVADED_FACTOR = 0.6;
+var SIGNAL_ORDER = [
+  "cadence",
+  "rest",
+  "repetition",
+  "longNote",
+  "pieceEnd",
+  "hypermeter"
+];
+function addSignal(boundaries, beat, signal, strength, cadence = null) {
+  const key = Math.round(beat / BEAT_EPS);
+  const existing = boundaries.get(key);
+  const boundary = existing ?? { beat, strengths: /* @__PURE__ */ new Map(), cadence: null };
+  boundary.strengths.set(signal, Math.max(boundary.strengths.get(signal) ?? 0, strength));
+  if (cadence !== null && boundary.cadence === null) {
+    boundary.cadence = cadence;
+  }
+  boundaries.set(key, boundary);
+}
+function readBoundary(boundary) {
+  const signals = [...boundary.strengths.entries()].sort(
+    (a, b) => b[1] - a[1] || SIGNAL_ORDER.indexOf(a[0]) - SIGNAL_ORDER.indexOf(b[0])
+  );
+  return {
+    strength: combineEvidence(signals.map(([, strength]) => strength)),
+    signals: signals.map(([signal]) => signal)
+  };
+}
+function lengthFit(length, expected) {
+  if (!(expected > 0)) {
+    return 0;
+  }
+  return Math.max(-1, 1 - Math.abs(length - expected) / expected);
+}
+function choosePhrasePath(beats, strengths, minPhraseBeats, expected) {
+  const value = new Array(beats.length).fill(Number.NEGATIVE_INFINITY);
+  const cameFrom = new Array(beats.length).fill(-1);
+  value[0] = 0;
+  for (let j = 1; j < beats.length; j += 1) {
+    const endBeat = beats[j] ?? 0;
+    for (let i = 0; i < j; i += 1) {
+      if (!Number.isFinite(value[i] ?? Number.NEGATIVE_INFINITY)) {
+        continue;
+      }
+      const length = endBeat - (beats[i] ?? 0);
+      if (length < minPhraseBeats - BEAT_EPS) {
+        continue;
+      }
+      const gain = (value[i] ?? 0) + (strengths[j] ?? 0) + lengthFit(length, expected) - PHRASE_CUT_COST;
+      if (gain > (value[j] ?? Number.NEGATIVE_INFINITY)) {
+        value[j] = gain;
+        cameFrom[j] = i;
+      }
+    }
+  }
+  const last = beats.length - 1;
+  const path = [];
+  if (last > 0 && Number.isFinite(value[last] ?? Number.NEGATIVE_INFINITY)) {
+    for (let i = last; i > 0; i = cameFrom[i] ?? 0) {
+      path.push(i);
+    }
+    path.reverse();
+  } else if (last > 0) {
+    path.push(last);
+  }
+  return path;
+}
+function arrivalEnd(timeline, atBeat) {
+  return segmentStartingAt(timeline.segments, atBeat)?.endBeat ?? atBeat;
+}
+function barSpanOf(startBeat, endBeat, meters) {
+  const firstBar = barIndexAt(startBeat, meters);
+  const lastBar = barIndexAt(endBeat, meters);
+  const partOf = (beat, bar) => {
+    const barStart = barPositionToBeat({ bar, beat: 0 }, meters);
+    const barLength = beatsPerBarAt(barStart, meters);
+    return barLength > 0 ? (beat - barStart) / barLength : 0;
+  };
+  const bars = lastBar - firstBar + partOf(endBeat, lastBar) - partOf(startBeat, firstBar);
+  return Math.round(bars * 100) / 100;
+}
+function keyContextFor(opts, notes, meters, totalBeats) {
+  if (opts.key !== void 0) {
+    return opts.key;
+  }
+  const regions = keyTimelineFromNotes(notes, {
+    meters,
+    totalBeats,
+    budget: opts.budget
+  });
+  const keyAt = keyLookup(regions, prevailingKeyOf(regions) ?? resolveKey(majorKey(0)));
+  return (beat) => scaleOf(keyAt(beat));
+}
+function restBoundaries(boundaries, notes, meters, restBeats) {
+  const ordered = [...notes].sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
+  let covered = Number.NEGATIVE_INFINITY;
+  for (const note of ordered) {
+    const gap = note.startBeat - covered;
+    if (Number.isFinite(covered) && gap >= restBeats - BEAT_EPS) {
+      const bar = beatsPerBarAt(note.startBeat, meters);
+      addSignal(
+        boundaries,
+        note.startBeat,
+        "rest",
+        REST_STRENGTH * clamp01(bar > 0 ? gap / bar : 1)
+      );
+    }
+    covered = Math.max(covered, note.startBeat + note.durationBeat);
+  }
+}
+function repetitionBoundaries(boundaries, notes, meters, spanStart, spanEnd, windowBeats, budget) {
+  if (!(windowBeats > 0)) {
+    return;
+  }
+  const slices = sliceBars(notes, meters, spanStart, spanEnd, budget);
+  assertGenerationBudget(slices.length * notes.length, "form repetition comparisons", budget);
+  const onsetsIn = (from, to) => notes.filter((note) => note.startBeat >= from - BEAT_EPS && note.startBeat < to - BEAT_EPS);
+  let comparisons = 0;
+  for (const slice of slices) {
+    const beat = slice.startBeat;
+    if (beat - windowBeats < spanStart - BEAT_EPS || beat + windowBeats > spanEnd + BEAT_EPS) {
+      continue;
+    }
+    const before = onsetsIn(beat - windowBeats, beat);
+    const after = onsetsIn(beat, beat + windowBeats);
+    if (before.length < 2 || after.length < 2) {
+      continue;
+    }
+    comparisons += before.length * after.length;
+    assertGenerationBudget(comparisons, "form repetition melody comparisons", budget);
+    const similarity = melodicSimilarity(before, after);
+    if (similarity >= REPETITION_THRESHOLD) {
+      addSignal(boundaries, beat, "repetition", REPETITION_STRENGTH * similarity);
+    }
+  }
+}
+function structuralWeightOf(cadence, confidence, aligned, isLast) {
+  if (cadence === null || cadence.cadence.type === null) {
+    return 0;
+  }
+  const result = cadence.cadence;
+  let base = CADENCE_CLOSURE[result.type];
+  if (result.type === "authentic") {
+    if (result.strength === "perfect") {
+      base = 1;
+    } else if (result.strength === "imperfect") {
+      base *= 0.8;
+    }
+  }
+  if (result.evaded) {
+    base *= EVADED_FACTOR;
+  }
+  let weight = base * confidence;
+  if (isLast) {
+    weight += FINAL_PHRASE_BONUS;
+  }
+  if (aligned) {
+    weight += HYPERMETRIC_CLOSE_BONUS;
+  }
+  return clamp01(weight);
+}
+function describeCadence(cadence) {
+  if (cadence === null || cadence.cadence.type === null) {
+    return "no cadence";
+  }
+  const { type, strength } = cadence.cadence;
+  const graded = strength === null ? type : `${strength} ${type}`;
+  return `a ${graded} cadence at beat ${cadence.atBeat}`;
+}
+function phrasesFromTimeline(timeline, notes, opts = {}) {
+  assertChordTimeline(timeline);
+  const meters = resolveMeters(opts, "phrase meters");
+  assertNoteEvents(notes, "phrase notes", {
+    allowNonPositiveDuration: true,
+    budget: opts.budget
+  });
+  if (opts.hypermeter !== void 0) {
+    assertRange(opts.hypermeter.confidence, 0, 1, "phrase hypermeter confidence");
+    assertPositiveInt(opts.hypermeter.groupBars, "phrase hypermeter groupBars");
+  }
+  const sounding = notes.filter((note) => note.durationBeat > 0);
+  const segments = timeline.segments;
+  const firstSegment = segments[0];
+  const lastSegment = segments[segments.length - 1];
+  const firstOnset = sounding.reduce(
+    (first, n) => Math.min(first, n.startBeat),
+    firstSegment?.startBeat ?? 0
+  );
+  const spanStart = barGridStart(firstOnset, meters);
+  const notesEnd = sounding.reduce(
+    (end, n) => Math.max(end, n.startBeat + n.durationBeat),
+    lastSegment?.endBeat ?? 0
+  );
+  const spanEnd = Math.max(spanStart, opts.totalBeats ?? notesEnd);
+  assertRange(spanEnd, 0, Number.MAX_SAFE_INTEGER, "phrase totalBeats");
+  if (spanEnd <= spanStart + BEAT_EPS) {
+    return [];
+  }
+  const barBeats = beatsPerBarAt(Math.max(0, spanStart), meters);
+  const restBeats = opts.restBeats ?? barBeats / 2;
+  assertRange(restBeats, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "phrase restBeats");
+  const longNoteBeats = opts.longNoteBeats ?? barBeats;
+  assertRange(longNoteBeats, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "phrase longNoteBeats");
+  const minPhraseBeats = opts.minPhraseBeats ?? barBeats;
+  assertRange(minPhraseBeats, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "phrase minPhraseBeats");
+  const key = keyContextFor(opts, sounding, meters, spanEnd);
+  const cadences = detectCadences(timeline, key);
+  const grouping = opts.hypermeter ?? hypermeter(sounding, meters, {
+    totalBeats: spanEnd,
+    cadenceBeats: cadences.map((hit) => hit.atBeat),
+    budget: opts.budget
+  });
+  const firstBar = barIndexAt(Math.max(0, spanStart), meters);
+  const hyperBeats = Math.max(
+    barBeats,
+    barPositionToBeat({ bar: firstBar + grouping.groupBars, beat: 0 }, meters) - barPositionToBeat({ bar: firstBar, beat: 0 }, meters)
+  );
+  const expected = opts.expectedPhraseBeats ?? hyperBeats;
+  assertRange(expected, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "phrase expectedPhraseBeats");
+  const boundaries = /* @__PURE__ */ new Map();
+  for (const hit of cadences) {
+    const type = hit.cadence.type;
+    if (type === null) {
+      continue;
+    }
+    const strength = CADENCE_BOUNDARY_STRENGTH[type];
+    const chordEnd = arrivalEnd(timeline, hit.atBeat);
+    addSignal(boundaries, chordEnd, "cadence", strength, hit);
+    const barEnd = barPositionToBeat({ bar: barIndexAt(hit.atBeat, meters) + 1, beat: 0 }, meters);
+    if (chordEnd > barEnd + BEAT_EPS) {
+      addSignal(boundaries, barEnd, "cadence", strength, hit);
+    }
+  }
+  restBoundaries(boundaries, sounding, meters, restBeats);
+  for (const note of sounding) {
+    if (note.durationBeat >= longNoteBeats - BEAT_EPS) {
+      addSignal(boundaries, note.startBeat + note.durationBeat, "longNote", LONG_NOTE_STRENGTH);
+    }
+  }
+  repetitionBoundaries(boundaries, sounding, meters, spanStart, spanEnd, hyperBeats, opts.budget);
+  for (const downbeat of grouping.downbeats) {
+    addSignal(boundaries, downbeat, "hypermeter", HYPERMETER_STRENGTH * grouping.confidence);
+  }
+  addSignal(boundaries, spanEnd, "pieceEnd", PIECE_END_STRENGTH);
+  const candidates = [...boundaries.values()].filter(
+    (boundary) => boundary.beat > spanStart + BEAT_EPS && boundary.beat < spanEnd - BEAT_EPS
+  ).filter((boundary) => readBoundary(boundary).strength > 0).sort((a, b) => a.beat - b.beat);
+  const endBoundary = boundaries.get(Math.round(spanEnd / BEAT_EPS)) ?? {
+    beat: spanEnd,
+    strengths: /* @__PURE__ */ new Map(),
+    cadence: null
+  };
+  const stops = [
+    { beat: spanStart, strengths: /* @__PURE__ */ new Map(), cadence: null },
+    ...candidates,
+    endBoundary
+  ];
+  assertGenerationBudget(stops.length * stops.length, "form phrase boundary pairs", opts.budget);
+  const readings = stops.map(readBoundary);
+  const path = choosePhrasePath(
+    stops.map((stop) => stop.beat),
+    readings.map((reading) => reading.strength),
+    minPhraseBeats,
+    expected
+  );
+  const downbeatKeys = new Set(
+    grouping.downbeats.map((downbeat) => Math.round(downbeat / BEAT_EPS))
+  );
+  const phrases = [];
+  let from = 0;
+  for (let n = 0; n < path.length; n += 1) {
+    const to = path[n] ?? stops.length - 1;
+    const startBeat = stops[from]?.beat ?? spanStart;
+    const stop = stops[to];
+    const endBeat = stop?.beat ?? spanEnd;
+    const reading = readings[to] ?? { strength: 0, signals: [] };
+    const length = endBeat - startBeat;
+    const confidence = clamp01(
+      CLOSING_SHARE * reading.strength + (1 - CLOSING_SHARE) * Math.max(0, lengthFit(length, expected))
+    );
+    const isLast = n === path.length - 1;
+    const closing = stop?.cadence ?? null;
+    const cadence = closing !== null && closing.atBeat >= startBeat - BEAT_EPS && closing.atBeat < endBeat - BEAT_EPS ? closing : null;
+    const structuralWeight = structuralWeightOf(
+      cadence,
+      confidence,
+      downbeatKeys.has(Math.round(endBeat / BEAT_EPS)),
+      isLast
+    );
+    const signals = cadence === null ? reading.signals.filter((signal) => signal !== "cadence") : reading.signals;
+    const bars = barSpanOf(startBeat, endBeat, meters);
+    phrases.push({
+      startBeat,
+      endBeat,
+      cadence,
+      signals,
+      confidence,
+      structuralWeight,
+      rationale: `Phrase of ${bars} bar(s) closing on ${describeCadence(cadence)}; boundary from ${signals.length === 0 ? "the end of the span" : signals.join(", ")}`
+    });
+    from = to;
+  }
+  return phrases;
+}
+function structuralCadences(phrases) {
+  assertArray(phrases, "phrases");
+  const ranked = [];
+  for (let index = 0; index < phrases.length; index += 1) {
+    const phrase = assertRecord(phrases[index], `phrases[${index}]`);
+    if (phrase.cadence === null || phrase.cadence === void 0 || phrase.cadence.cadence.type === null) {
+      continue;
+    }
+    const hit = phrase.cadence;
+    ranked.push({
+      phraseIndex: index,
+      atBeat: hit.atBeat,
+      endBeat: phrase.endBeat,
+      cadence: hit.cadence,
+      weight: phrase.structuralWeight,
+      rationale: `Closes ${describeCadence(hit)} on a phrase of confidence ${Math.round(phrase.confidence * 100) / 100}`
+    });
+  }
+  return ranked.sort((a, b) => b.weight - a.weight || a.atBeat - b.atBeat);
+}
+
+// src/analyze/form/section.ts
+var MELODY_SHARE = 0.6;
+var HARMONY_SHARE = 0.4;
+var DEFAULT_THRESHOLD = 0.8;
+function labelAt(index) {
+  let n = index;
+  let label = "";
+  do {
+    label = String.fromCharCode(65 + n % 26) + label;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return label;
+}
+function isSilent(unit) {
+  return unit.notes.length === 0;
+}
+function unitSimilarity(a, b) {
+  const harmony = weightSimilarity(a.weights, b.weights);
+  if (a.notes.length < 2 || b.notes.length < 2) {
+    return a.notes.length === b.notes.length ? harmony : 0;
+  }
+  const melody = melodicSimilarity(a.notes, b.notes);
+  return clamp01(MELODY_SHARE * melody + HARMONY_SHARE * harmony);
+}
+function sectionsFromNotes(notes, opts = {}) {
+  const meters = resolveMeters(opts, "section meters");
+  assertNoteEvents(notes, "section notes", {
+    allowNonPositiveDuration: true,
+    budget: opts.budget
+  });
+  const sounding = notes.filter((note) => note.durationBeat > 0);
+  if (sounding.length === 0) {
+    return [];
+  }
+  const firstOnset = barGridStart(firstSoundingBeat(sounding), meters);
+  const lastEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  const spanEnd = Math.max(firstOnset, opts.totalBeats ?? lastEnd);
+  assertRange(spanEnd, 0, Number.MAX_SAFE_INTEGER, "section totalBeats");
+  const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+  assertRange(threshold, 0, 1, "section threshold");
+  const unitBars = opts.unitBars ?? hypermeter(sounding, meters, { totalBeats: spanEnd, budget: opts.budget }).groupBars;
+  assertPositiveInt(unitBars, "section unitBars");
+  const firstBar = barIndexAt(firstOnset, meters);
+  const lastBar = lastBarOf(meters, firstOnset, spanEnd);
+  const startBar = Math.max(0, firstBar);
+  const unitCount = Math.max(1, Math.ceil((lastBar - startBar + 1) / unitBars));
+  assertGenerationBudget(unitCount * unitCount, "form section comparisons", opts.budget);
+  assertGenerationBudget(unitCount * sounding.length, "form section unit notes", opts.budget);
+  const units = [];
+  for (let index = 0; index < unitCount; index += 1) {
+    const barStart = startBar + index * unitBars;
+    const startBeat = index === 0 ? firstOnset : barPositionToBeat({ bar: barStart, beat: 0 }, meters);
+    const endBeat = index === unitCount - 1 ? spanEnd : barPositionToBeat({ bar: barStart + unitBars, beat: 0 }, meters);
+    const unitNotes = sounding.filter(
+      (note) => note.startBeat >= startBeat - BEAT_EPS && note.startBeat < endBeat - BEAT_EPS
+    ).sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
+    units.push({
+      startBeat,
+      endBeat,
+      notes: unitNotes,
+      weights: windowWeights(unitNotes, startBeat, endBeat, meters).weights
+    });
+  }
+  let comparisons = 0;
+  let earlierNotes = 0;
+  for (const unit of units) {
+    comparisons += unit.notes.length * earlierNotes;
+    earlierNotes += unit.notes.length;
+  }
+  assertGenerationBudget(comparisons, "form section melody comparisons", opts.budget);
+  const labels = [];
+  const scores = [];
+  let distinct = 0;
+  for (let index = 0; index < units.length; index += 1) {
+    const unit = units[index];
+    if (unit === void 0) {
+      continue;
+    }
+    if (isSilent(unit)) {
+      labels.push(null);
+      scores.push(scores[index - 1] ?? 1);
+      continue;
+    }
+    let bestScore = -1;
+    let bestIndex = -1;
+    for (let earlier = 0; earlier < index; earlier += 1) {
+      const other = units[earlier];
+      if (other === void 0 || isSilent(other)) {
+        continue;
+      }
+      const score = unitSimilarity(unit, other);
+      if (score > bestScore) {
+        bestScore = score;
+        bestIndex = earlier;
+      }
+    }
+    if (bestIndex >= 0 && bestScore >= threshold) {
+      labels.push(labels[bestIndex] ?? labelAt(distinct));
+      scores.push(bestScore);
+    } else {
+      labels.push(labelAt(distinct));
+      scores.push(1);
+      distinct += 1;
+    }
+  }
+  const sections = [];
+  const firstByLabel = /* @__PURE__ */ new Map();
+  for (let index = 0; index < units.length; ) {
+    const label = labels[index] ?? null;
+    if (label === null) {
+      index += 1;
+      continue;
+    }
+    let end = index;
+    let scoreSum = 0;
+    let sounded = 0;
+    while (end < units.length && labels[end] === label) {
+      scoreSum += scores[end] ?? 1;
+      sounded += 1;
+      end += 1;
+    }
+    while (end < units.length && labels[end] === null) {
+      end += 1;
+    }
+    const startBeat = units[index]?.startBeat ?? 0;
+    const endBeat = units[end - 1]?.endBeat ?? spanEnd;
+    const sectionFirstBar = startBar + index * unitBars;
+    const sectionLastBar = Math.max(
+      sectionFirstBar,
+      Math.min(lastBar, startBar + end * unitBars - 1)
+    );
+    const sectionIndex = sections.length;
+    const first = firstByLabel.get(label);
+    if (first === void 0) {
+      firstByLabel.set(label, sectionIndex);
+    }
+    const similarity = first === void 0 ? 1 : clamp01(scoreSum / Math.max(1, sounded));
+    sections.push({
+      label,
+      startBeat,
+      endBeat,
+      bars: sectionLastBar - sectionFirstBar + 1,
+      firstOccurrence: first ?? sectionIndex,
+      similarity,
+      rationale: first === void 0 ? `Section ${label}: material first heard at beat ${startBeat}` : `Section ${label}: ${Math.round(similarity * 100)}% alike the ${label} at beat ${sections[first]?.startBeat ?? 0}`
+    });
+    index = end;
+  }
+  return sections;
+}
+
+// src/analyze/reduction/index.ts
+var TONIC_ARRIVING = /* @__PURE__ */ new Set(["authentic", "plagal", "modal", "deceptive"]);
+function signedStep(fromPc, toPc) {
+  return (pitchClassOf(toPc) - pitchClassOf(fromPc) + 18) % 12 - 6;
+}
+function isStep(distance) {
+  const size = Math.abs(distance);
+  return size === 1 || size === 2;
+}
+function touches(before, after) {
+  return Math.abs(after.startBeat - before.endBeat) <= BEAT_EPS;
+}
+function salienceFloors(durations) {
+  const order = durations.map((_, index) => index).sort((a, b) => {
+    const left = durations[a] ?? 0;
+    const right = durations[b] ?? 0;
+    return left - right || a - b;
+  });
+  const rankOf = new Array(durations.length).fill(0);
+  for (let rank = 0; rank < order.length; rank += 1) {
+    rankOf[order[rank] ?? 0] = rank;
+  }
+  const floors = [];
+  const remaining = durations.length - 1;
+  for (let index = 0; index < durations.length; index += 1) {
+    if (remaining <= 0) {
+      floors.push(0);
+      continue;
+    }
+    const skipped = rankOf[index] ?? 0;
+    const at = (position) => durations[order[position < skipped ? position : position + 1] ?? 0] ?? 0;
+    const middle = remaining >> 1;
+    floors.push(remaining % 2 === 1 ? at(middle) : (at(middle - 1) + at(middle)) / 2);
+  }
+  return floors;
+}
+function isTonicChord(chord, key) {
+  return pitchClassOf(chord.rootPc - key.rootPc) === 0 && !isAppliedDominant(chord, key);
+}
+function functionalReason(segment, before, after, keyAt) {
+  const key = keyAt(segment.startBeat);
+  if (after !== void 0 && isCadentialSixFour(segment.chord, after.chord, key)) {
+    return { kind: "cadentialSixFour" };
+  }
+  if (isTonicChord(segment.chord, key)) {
+    return { kind: "tonic" };
+  }
+  if (isDominantChordOf(segment.chord, key)) {
+    return { kind: "dominant" };
+  }
+  if (before !== void 0) {
+    const arrival = detectCadence(before.chord, segment.chord, key).type;
+    if (arrival !== null) {
+      return { kind: "cadenceArrival", cadence: arrival };
+    }
+  }
+  if (after !== void 0) {
+    const agent = detectCadence(segment.chord, after.chord, keyAt(after.startBeat)).type;
+    if (agent !== null && TONIC_ARRIVING.has(agent)) {
+      return { kind: "cadenceAgent", cadence: agent };
+    }
+  }
+  return null;
+}
+function figureReason(segment, before, after) {
+  if (before === void 0 || after === void 0) {
+    return null;
+  }
+  const incoming = signedStep(before.chord.rootPc, segment.chord.rootPc);
+  const outgoing = signedStep(segment.chord.rootPc, after.chord.rootPc);
+  if (!isStep(incoming) || !isStep(outgoing)) {
+    return null;
+  }
+  if (incoming > 0 === outgoing > 0) {
+    return { kind: "passing" };
+  }
+  return pitchClassOf(before.chord.rootPc) === pitchClassOf(after.chord.rootPc) ? { kind: "neighbor" } : null;
+}
+function describe(reason) {
+  switch (reason.kind) {
+    case "tonic":
+      return "Structural: the tonic of the key, which the progression is heard against";
+    case "dominant":
+      return "Structural: the dominant of the key, the chord its tonic is approached from";
+    case "cadentialSixFour":
+      return "Structural: a tonic six-four on the bass of the dominant that follows, which prolongs that dominant rather than framing the tonic";
+    case "cadenceArrival":
+      return `Structural: the arrival of a ${reason.cadence} cadence`;
+    case "cadenceAgent":
+      return `Structural: the chord that drives a ${reason.cadence} cadence`;
+    case "salient":
+      return "Structural: it holds the harmony longer than the chords around it";
+    case "first":
+      return "Structural: the first chord of the progression frames it";
+    case "last":
+      return "Structural: the last chord of the progression frames it";
+    case "unfigured":
+      return "Structural: its root neither steps through to the next chord nor returns to the last, so it embellishes nothing";
+    case "passing":
+      return "Passing: its root steps in from the previous chord and on to the next in the same direction";
+    case "neighbor":
+      return "Neighbor: its root steps away from the surrounding harmony and returns to it";
+  }
+}
+var BASIS_READINGS = {
+  function: ({ segment, before, after, keyAt }) => functionalReason(segment, before, after, keyAt),
+  duration: ({ segment, salienceFloor }) => segment.endBeat - segment.startBeat > salienceFloor ? { kind: "salient" } : null
+};
+var REDUCTION_BASES = Object.keys(BASIS_READINGS);
+function levelOf(reason) {
+  if (reason.kind === "passing") {
+    return "passing";
+  }
+  return reason.kind === "neighbor" ? "neighbor" : "structural";
+}
+function reduceProgression(timeline, key, opts = {}) {
+  assertChordTimeline(timeline);
+  const asked = assertOptions(opts, "opts");
+  const keyAt = keyScaleAt(key);
+  const basis = assertOneOf(asked.basis ?? "function", REDUCTION_BASES, "reduction basis");
+  const reading = BASIS_READINGS[basis];
+  const segments = timeline.segments;
+  const floors = basis === "duration" ? salienceFloors(segments.map((segment) => segment.endBeat - segment.startBeat)) : [];
+  const result = [];
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index];
+    if (segment === void 0) {
+      continue;
+    }
+    const previous = segments[index - 1];
+    const following = segments[index + 1];
+    const before = previous !== void 0 && touches(previous, segment) ? previous : void 0;
+    const after = following !== void 0 && touches(segment, following) ? following : void 0;
+    let reason = reading({ segment, before, after, keyAt, salienceFloor: floors[index] ?? 0 });
+    if (reason === null && index === 0) {
+      reason = { kind: "first" };
+    }
+    if (reason === null && index === segments.length - 1) {
+      reason = { kind: "last" };
+    }
+    reason ??= figureReason(segment, before, after) ?? { kind: "unfigured" };
+    result.push({
+      chord: segment.chord,
+      startBeat: segment.startBeat,
+      endBeat: segment.endBeat,
+      level: levelOf(reason),
+      rationale: describe(reason)
+    });
+  }
+  return result;
+}
+
+export {
+  trackRoleOf,
+  analyzePolyphony,
+  analyzeArrangement,
+  createArrangementSession,
+  tensionCurve,
+  tensionCurveFrom,
+  hypermeter,
+  melodicContour,
+  extractMotifs,
+  motifFromNotes,
+  relateMotifs,
+  compareMelodies,
+  melodicSimilarity,
+  phrasesFromTimeline,
+  structuralCadences,
+  sectionsFromNotes,
+  reduceProgression
+};
+//# sourceMappingURL=chunk-HYJJ2V2I.js.map