@libraz/libcantus 1.1.0 → 1.3.0

package/dist/{chunk-HSY2VQXZ.js → chunk-MLBPXA4Z.js}

@@ -1,47 +1,66 @@
 import {
-  HUMANIZE_ADJACENCY,
+  REFERENCE_PROFILE_VERSION,
   adjacent,
+  analyzeRhythm,
   analyzeTimeline,
   analyzeVoice,
   assertChordTimeline,
+  assertReferenceProfile,
   attachPivots,
   barGridStart,
+  barSpanOf,
+  cadenceSimilarity,
   chordTimelineFromNotes,
+  chordToRoman,
   clamp01,
   combineEvidence,
-  detectCadence,
+  contourSimilarity,
+  densitySimilarity,
   detectCadences,
   dirtySlotsFor,
+  durationSimilarity,
+  extractMotifs,
   firstSoundingBeat,
   floorMod,
   functionOf,
+  functionSimilarity,
   gridForNotes,
   harmonicNovelty,
   hasEnded,
-  isAppliedDominant,
-  isCadentialSixFour,
   keyLookup,
-  keyScaleAt,
+  keyPlanSimilarity,
   keyTimelineFromNotes,
   lastBarOf,
+  melodicContour,
+  melodicSimilarity,
+  motifGraph,
+  motifStructureSimilarity,
+  onsetSimilarity,
+  orderedNotes,
+  phraseLengthSimilarity,
+  phraseMelody,
   prevailingKeyOf,
+  progressionSimilarity,
+  reduceProgression,
+  registerSimilarity,
   sameInstant,
+  sectionSequenceSimilarity,
   segmentStartingAt,
   sliceBars,
+  surfaceSimilarity,
+  syncopationSimilarity,
   weightSimilarity,
+  weightedMean,
   windowWeights
-} from "./chunk-VLE5R7PF.js";
+} from "./chunk-GNVN4PPJ.js";
 import {
   PROFILE_WEIGHTS,
   chordPitchClasses,
   evaluateSafety,
-  isDominantChordOf,
-  keySignatureFifths,
   majorKey,
   resolveKey,
-  scaleOf,
-  scaleTonesInDegreeOrder
-} from "./chunk-FPBZFNCD.js";
+  scaleOf
+} from "./chunk-RFIBF2RR.js";
 import {
   BEAT_EPS,
   InvalidInputError,
@@ -61,11 +80,9 @@ import {
   beatsPerBarAt,
   describeRejected,
   isStrongBeat,
-  midiToNote,
   pitchClassOf,
-  resolveMeters,
-  spelledInterval
-} from "./chunk-PQL7E5F6.js";
+  resolveMeters
+} from "./chunk-AGOVW7U6.js";
 
 // src/analyze/arrange/internal.ts
 var MAX_LANE_LEAP = 24;
@@ -328,6 +345,8 @@ function prepareTracks(tracks) {
         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,
@@ -395,7 +414,7 @@ function soundingVoicesAt(prepared, beat) {
       if (previous !== void 0) {
         snap.prevPitch = previous;
       }
-      out.push({ track: t, voice: v, snapshot: snap });
+      out.push({ track: t, voice: v, trackIndex: track.trackIndex, note, snapshot: snap });
     }
   }
   return out;
@@ -403,7 +422,21 @@ function soundingVoicesAt(prepared, beat) {
 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).map(({ snapshot }) => snapshot);
+  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 });
@@ -425,7 +458,7 @@ function analyzePolyphony(notes, chordAtBeat, key) {
       subVoice.voice,
       chordAtBeat,
       key,
-      (beat) => otherVoicesSounding(prepared, 0, v, beat, soundingCache)
+      (beat) => snapshotsOf(otherVoicesSounding(prepared, 0, v, beat, soundingCache))
     );
     for (const note of analyzed) {
       if (note.originalIndex !== void 0) {
@@ -549,7 +582,7 @@ function analyzeArrangementWith(tracks, opts = {}, previous, dirty) {
         subVoice.voice,
         timeline.at,
         scaleAt,
-        (beat) => otherVoicesSounding(prepared, t, v, beat, soundingCache)
+        (beat) => snapshotsOf(otherVoicesSounding(prepared, t, v, beat, soundingCache))
       );
       for (const note of analyzed) {
         notes.push({ ...note, trackIndex: track.trackIndex });
@@ -563,18 +596,19 @@ function analyzeArrangementWith(tracks, opts = {}, previous, dirty) {
         }
         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: otherVoicesSounding(prepared, t, v, beat, soundingCache),
+            otherVoices: snapshotsOf(others),
             strongBeat: isStrongBeat(beat, meters)
           };
           let result = evaluateSafety(safetyQuery, { suggestions: false });
           if (result.safety !== 0 /* Safe */ && result.safety >= minSeverity) {
-            result = evaluateSafety(safetyQuery);
+            result = evaluateSafety(safetyQuery, { partners: true });
             const conflict = {
               beat,
               trackName: track.name,
@@ -597,6 +631,11 @@ function analyzeArrangementWith(tracks, opts = {}, previous, dirty) {
             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);
           }
         }
@@ -1052,549 +1091,6 @@ function hypermeter(notes, meter, opts = {}) {
   };
 }
 
-// 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,
@@ -1692,17 +1188,6 @@ function choosePhrasePath(beats, strengths, minPhraseBeats, expected) {
 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;
@@ -1912,7 +1397,7 @@ function phrasesFromTimeline(timeline, notes, opts = {}) {
       isLast
     );
     const signals = cadence === null ? reading.signals.filter((signal) => signal !== "cadence") : reading.signals;
-    const bars = barSpanOf(startBeat, endBeat, meters);
+    const bars = Math.round(barSpanOf(startBeat, endBeat, meters) * 100) / 100;
     phrases.push({
       startBeat,
       endBeat,
@@ -2098,156 +1583,277 @@ function sectionsFromNotes(notes, opts = {}) {
   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;
+// src/analyze/reference/compare.ts
+var RATIONALE_FIELDS = 2;
+function rationaleOf(comparison) {
+  const measured = [];
+  for (const group of [comparison.form, comparison.harmony, comparison.melody, comparison.rhythm]) {
+    for (const [name, value] of Object.entries(group)) {
+      if (value !== null) {
+        measured.push({ name, value, order: measured.length });
+      }
     }
-    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";
+  if (measured.length === 0) {
+    return "Nothing to compare: neither profile has material for any field";
+  }
+  const describe = (entries) => entries.map((entry) => `${entry.name} ${Math.round(entry.value * 100)}%`).join(", ");
+  const highest = [...measured].sort((x, y) => y.value - x.value || x.order - y.order);
+  const lowest = [...measured].sort((x, y) => x.value - y.value || x.order - y.order);
+  return `Most alike: ${describe(highest.slice(0, RATIONALE_FIELDS))}; least alike: ${describe(lowest.slice(0, RATIONALE_FIELDS))}`;
+}
+function compareReferences(a, b, opts) {
+  assertReferenceProfile(a, "reference profile a");
+  assertReferenceProfile(b, "reference profile b");
+  const { budget } = assertOptions(opts, "compare options");
+  const structural = (profile) => profile.harmony.chords.filter((chord) => chord.level === "structural");
+  const cadences = (profile) => profile.form.phrases.map((phrase) => phrase.cadence?.type ?? null);
+  const phraseMelodies = (profile) => profile.form.phrases.map((phrase) => phrase.melody);
+  const comparison = {
+    form: {
+      sectionSequenceSimilarity: sectionSequenceSimilarity(
+        a.form.sections.map((section) => section.label),
+        b.form.sections.map((section) => section.label)
+      ),
+      phraseLengthSimilarity: phraseLengthSimilarity(
+        a.form.phrases.map((phrase) => phrase.bars),
+        b.form.phrases.map((phrase) => phrase.bars)
+      )
+    },
+    harmony: {
+      progressionSimilarity: progressionSimilarity(structural(a), structural(b), budget),
+      functionSimilarity: functionSimilarity(a.harmony.chords, b.harmony.chords),
+      cadenceSimilarity: cadenceSimilarity(cadences(a), cadences(b)),
+      keyPlanSimilarity: keyPlanSimilarity(
+        a.harmony.keys.map((region) => region.key),
+        b.harmony.keys.map((region) => region.key)
+      ),
+      harmonicRhythmOnsetSimilarity: onsetSimilarity(a.harmony.rhythm, b.harmony.rhythm),
+      harmonicRhythmDensitySimilarity: densitySimilarity(a.harmony.rhythm, b.harmony.rhythm)
+    },
+    melody: {
+      surfaceSimilarity: surfaceSimilarity(a.melody.motifs, b.melody.motifs),
+      motifStructureSimilarity: motifStructureSimilarity(
+        { graph: a.melody.graph, spanBeats: a.span.endBeat - a.span.startBeat },
+        { graph: b.melody.graph, spanBeats: b.span.endBeat - b.span.startBeat }
+      ),
+      contourSimilarity: contourSimilarity(phraseMelodies(a), phraseMelodies(b)),
+      registerSimilarity: registerSimilarity(
+        { phrases: phraseMelodies(a), mean: a.melody.register?.mean ?? null },
+        { phrases: phraseMelodies(b), mean: b.melody.register?.mean ?? null }
+      )
+    },
+    rhythm: {
+      onsetSimilarity: onsetSimilarity(a.melody.rhythm, b.melody.rhythm),
+      densitySimilarity: densitySimilarity(a.melody.rhythm, b.melody.rhythm),
+      durationSimilarity: durationSimilarity(a.melody.rhythm, b.melody.rhythm),
+      syncopationSimilarity: syncopationSimilarity(a.melody.rhythm, b.melody.rhythm)
+    }
+  };
+  return { ...comparison, rationale: rationaleOf(comparison) };
 }
-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];
+
+// src/analyze/reference/profile.ts
+function spanOf(sounding, timeline, meters, totalBeats) {
   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)
+  const firstSegment = segments[0];
+  const lastSegment = segments[segments.length - 1];
+  const firstOnset = firstSoundingBeat(sounding, firstSegment?.startBeat ?? 0);
+  const startBeat = barGridStart(
+    Math.min(firstOnset, firstSegment?.startBeat ?? firstOnset),
+    meters
+  );
+  const notesEnd = sounding.reduce(
+    (end, note) => Math.max(end, note.startBeat + note.durationBeat),
+    lastSegment?.endBeat ?? 0
+  );
+  return { startBeat, endBeat: Math.max(startBeat, totalBeats ?? notesEnd) };
+}
+function sameKey(a, b) {
+  return pitchClassOf(a.scale.rootPc) === pitchClassOf(b.scale.rootPc) && a.scale.modeMask12 === b.scale.modeMask12;
+}
+function keyIndexAt(regions, beat, prevailing) {
+  const holding = regions.findIndex((region) => region.startBeat <= beat && beat < region.endBeat);
+  if (holding >= 0) {
+    return holding;
+  }
+  return Math.max(
+    0,
+    regions.findIndex((region) => sameKey(region.key, prevailing))
+  );
+}
+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 readingsFor(notes, opts = {}) {
+  const asked = assertOptions(opts, "reference options");
+  const meters = resolveMeters(asked, "reference meters");
+  const budget = asked.budget;
+  if (asked.timeline === void 0) {
+    return chordTimelineFromNotes(notes, {
+      meters,
+      key: asked.key,
+      totalBeats: asked.totalBeats,
+      budget
     });
   }
-  return result;
+  const timeline = assertChordTimeline(asked.timeline, "reference timeline");
+  let keys;
+  if (asked.key === void 0) {
+    keys = keyTimelineFromNotes(notes, { meters, totalBeats: asked.totalBeats, budget });
+  } else {
+    const sounding = assertNoteEvents(notes, "reference notes", {
+      allowNonPositiveDuration: true,
+      budget
+    }).filter((note) => note.durationBeat > 0);
+    const span = spanOf(sounding, timeline, meters, asked.totalBeats);
+    keys = [
+      {
+        startBeat: span.startBeat,
+        endBeat: span.endBeat,
+        key: resolveKey(asked.key),
+        confidence: 1
+      }
+    ];
+  }
+  return { timeline, keys, prevailingKey: prevailingKeyOf(keys) ?? resolveKey(majorKey(0)) };
+}
+function referenceFromReadings(notes, readings, opts = {}) {
+  const asked = assertOptions(opts, "reference options");
+  const meters = resolveMeters(asked, "reference meters");
+  const budget = asked.budget;
+  const sounding = assertNoteEvents(notes, "reference notes", {
+    allowNonPositiveDuration: true,
+    budget
+  }).filter((note) => note.durationBeat > 0);
+  if (asked.totalBeats !== void 0) {
+    assertRange(asked.totalBeats, 0, Number.MAX_SAFE_INTEGER, "reference totalBeats");
+  }
+  const line = orderedNotes(asked.melody ?? notes, "reference melody", budget);
+  const { timeline, prevailingKey } = readings;
+  const span = spanOf(sounding, timeline, meters, asked.totalBeats);
+  const spanEnd = span.endBeat;
+  const keyAt = keyLookup(readings.keys, prevailingKey);
+  const scaleAt = (beat) => scaleOf(keyAt(beat));
+  const cadenceBeats = detectCadences(timeline, scaleAt).map((hit) => hit.atBeat);
+  const grouping = hypermeter(sounding, meters, { cadenceBeats, totalBeats: spanEnd, budget });
+  const phrases = phrasesFromTimeline(timeline, notes, {
+    meters,
+    key: scaleAt,
+    hypermeter: grouping,
+    totalBeats: spanEnd,
+    budget
+  });
+  const cadences = /* @__PURE__ */ new Map();
+  for (const closing of structuralCadences(phrases)) {
+    const type = closing.cadence.type;
+    if (type !== null) {
+      cadences.set(closing.phraseIndex, {
+        atBeat: closing.atBeat,
+        type,
+        weight: closing.weight
+      });
+    }
+  }
+  const sections = sectionsFromNotes(notes, {
+    meters,
+    unitBars: grouping.groupBars,
+    totalBeats: spanEnd,
+    budget
+  });
+  const keys = readings.keys.length === 0 && timeline.segments.length > 0 ? [
+    {
+      startBeat: span.startBeat,
+      endBeat: spanEnd,
+      key: resolveKey(prevailingKey),
+      confidence: 0
+    }
+  ] : readings.keys.map((region) => ({
+    startBeat: region.startBeat,
+    endBeat: region.endBeat,
+    key: resolveKey(region.key),
+    confidence: region.confidence
+  }));
+  const chords = reduceProgression(timeline, scaleAt).map((reduced) => {
+    const index = keyIndexAt(keys, (reduced.startBeat + reduced.endBeat) / 2, prevailingKey);
+    const key = keys[index].key;
+    return {
+      startBeat: reduced.startBeat,
+      endBeat: reduced.endBeat,
+      key: index,
+      roman: chordToRoman(reduced.chord, key),
+      function: functionOf(reduced.chord, key),
+      level: reduced.level
+    };
+  });
+  const chordOnsets = timeline.segments.map((segment) => ({
+    pitch: 60,
+    startBeat: segment.startBeat,
+    durationBeat: segment.endBeat - segment.startBeat
+  }));
+  const harmonyRhythm = analyzeRhythm(chordOnsets, { meters, totalBeats: spanEnd, budget });
+  const motifs = extractMotifs(line, { budget });
+  const graph = motifGraph(line, motifs, { key: prevailingKey, budget });
+  let register = null;
+  if (line.length > 0) {
+    const pitches = line.map((note) => note.pitch);
+    register = {
+      low: Math.min(...pitches),
+      high: Math.max(...pitches),
+      mean: weightedMean(line)
+    };
+  }
+  const lineMean = register?.mean ?? 0;
+  const referenceMotifs = motifs.map((motif) => {
+    const first = motif.occurrences[0];
+    return {
+      intervals: motif.intervals,
+      rhythm: motif.rhythm,
+      unitBeats: motif.notes.length < 2 ? 0 : motif.notes[1].startBeat - motif.notes[0].startBeat,
+      spanBeats: first === void 0 ? 0 : first.endBeat - first.startBeat,
+      occurrences: motif.occurrences.length
+    };
+  });
+  const referencePhrases = phrases.map((phrase, index) => ({
+    startBeat: phrase.startBeat,
+    endBeat: phrase.endBeat,
+    bars: barSpanOf(phrase.startBeat, phrase.endBeat, meters),
+    section: sectionAt(sections, phrase.startBeat),
+    confidence: phrase.confidence,
+    cadence: cadences.get(index) ?? null,
+    melody: phraseMelody(line, phrase.startBeat, phrase.endBeat, lineMean, meters, budget),
+    motifNodes: graph.nodes.flatMap(
+      (node, nodeIndex) => node.startBeat >= phrase.startBeat - BEAT_EPS && node.startBeat < phrase.endBeat - BEAT_EPS ? [nodeIndex] : []
+    )
+  }));
+  return {
+    profileVersion: REFERENCE_PROFILE_VERSION,
+    span: {
+      startBeat: span.startBeat,
+      endBeat: spanEnd,
+      bars: barSpanOf(span.startBeat, spanEnd, meters)
+    },
+    meters,
+    form: {
+      hypermeter: { groupBars: grouping.groupBars, confidence: grouping.confidence },
+      sections,
+      phrases: referencePhrases
+    },
+    harmony: { keys, chords, rhythm: harmonyRhythm },
+    melody: {
+      register,
+      shape: line.length < 2 ? null : melodicContour(line).shape,
+      motifs: referenceMotifs,
+      graph,
+      rhythm: analyzeRhythm(line, { meters, totalBeats: spanEnd, budget })
+    }
+  };
+}
+function analyzeReference(notes, opts) {
+  return referenceFromReadings(notes, readingsFor(notes, opts), opts);
 }
 
 export {
@@ -2258,15 +1864,11 @@ export {
   tensionCurve,
   tensionCurveFrom,
   hypermeter,
-  melodicContour,
-  extractMotifs,
-  motifFromNotes,
-  relateMotifs,
-  compareMelodies,
-  melodicSimilarity,
   phrasesFromTimeline,
   structuralCadences,
   sectionsFromNotes,
-  reduceProgression
+  compareReferences,
+  referenceFromReadings,
+  analyzeReference
 };
-//# sourceMappingURL=chunk-HSY2VQXZ.js.map
+//# sourceMappingURL=chunk-MLBPXA4Z.js.map