@libraz/libcantus 1.2.0 → 1.4.0

package/dist/{chunk-FBH75DAY.js → chunk-5MWRBYAT.js}

@@ -1,20 +1,22 @@
 import {
   analyzeArrangement,
   analyzePolyphony,
+  analyzeReference,
+  arrangementProfile,
+  assertTrackNotes,
+  boundaryCadences,
   createArrangementSession,
-  extractMotifs,
+  harmonyTrackSet,
   hypermeter,
-  melodicContour,
-  melodicSimilarity,
-  motifFromNotes,
+  hypermeterOver,
+  keyContextFor,
   phrasesFromTimeline,
-  reduceProgression,
-  relateMotifs,
+  referenceFromReadings,
   sectionsFromNotes,
   structuralCadences,
   tensionCurveFrom,
   trackRoleOf
-} from "./chunk-HYJJ2V2I.js";
+} from "./chunk-UTE5A36R.js";
 import {
   TWELVE_TET,
   beatsToDuration,
@@ -38,22 +40,25 @@ import {
   tempoAt,
   tempoReader,
   ticksToBeats
-} from "./chunk-UMWZ4ZET.js";
+} from "./chunk-7NQ6AL3H.js";
 import {
   STEP_BEATS,
   applyGrooveTemplate,
   cellSpan,
-  deform,
+  deformFigure,
+  deriveCompositionPlan,
   developMotif,
-  doubleTime,
+  doubleTimeFigure,
+  evaluateComposition,
   extractGrooveTemplate,
   generateBassLine,
   generateCounterMelody,
   generateDrums,
+  generateMelody,
   generateMotif,
   generateProgression,
   generateRhythm,
-  halfTime,
+  halfTimeFigure,
   harmonizeMelody,
   humanize,
   modalInterchangePalette,
@@ -62,6 +67,7 @@ import {
   ornament,
   ornamentBy,
   resolveContext,
+  resolveDials,
   rhythmDensity,
   rhythmToNoteEvents,
   substituteChord,
@@ -69,9 +75,11 @@ import {
   thin,
   transformMotif,
   withinCeiling
-} from "./chunk-Q6LFSAKV.js";
+} from "./chunk-FK3DGAIZ.js";
 import {
   analyzeChord,
+  analyzeRhythm,
+  assertSpansInOrder,
   augmentedSixthChord,
   borrowedSource,
   chordAtBeat,
@@ -87,17 +95,25 @@ import {
   detectKeyFromNotes,
   detectModulations,
   explainRoman,
+  extractMotifs,
   functionOf,
   isBorrowedChord,
   isMinorKey,
   keyLookup,
   keyTimelineFromNotes,
+  melodicContour,
+  melodicSimilarity,
+  motifFromNotes,
+  motifGraph,
   pivotChords,
   prevailingKeyOf,
+  reduceProgression,
+  relateMotifs,
   romanToChord,
   secondaryDominantOf,
+  statedKeyRegions,
   toVoiceNotes
-} from "./chunk-H2KJHBW4.js";
+} from "./chunk-FJFULJZE.js";
 import {
   BASS_4_STRING,
   BASS_5_STRING,
@@ -110,10 +126,10 @@ import {
   soundsIn,
   toInstrumentProfile,
   toStringedProfile
-} from "./chunk-7KG3RTYS.js";
+} from "./chunk-VL5NXVCN.js";
 import {
   createNoteEventIndex
-} from "./chunk-PUKJP2Z5.js";
+} from "./chunk-TXFWSU5D.js";
 import {
   SATB_RANGES,
   checkPartWriting,
@@ -128,14 +144,14 @@ import {
   voiceChordStyled,
   voiceLeadingCost,
   voiceProgression
-} from "./chunk-M5RYMAFI.js";
+} from "./chunk-ZLNSH4UL.js";
 import {
   availableTensions,
   avoidNotes,
   chordScaleReport,
   chordScales,
   scalesForChanges
-} from "./chunk-NB25P3EH.js";
+} from "./chunk-2G5MCGYU.js";
 import {
   NAMED_SCALES,
   assertChordQuality,
@@ -146,6 +162,7 @@ import {
   chordSpecOf,
   chordToneRole,
   chordToneSpellings,
+  classifySpelledInterval,
   diatonicPitchClasses,
   diatonicSeventh,
   diatonicTriad,
@@ -191,10 +208,11 @@ import {
   tryResolveKeyName,
   variantOfMask,
   voiceIndependence
-} from "./chunk-RFIBF2RR.js";
+} from "./chunk-H7FVMBUC.js";
 import {
   InvalidInputError,
   MAX_NAME_ACCIDENTALS,
+  assertArray,
   assertFiniteNumber,
   assertInteger,
   assertMidiPitch,
@@ -202,9 +220,11 @@ import {
   assertOneOf,
   assertPositiveInt,
   assertRange,
+  assertRecord,
   assertTimeSignature,
   beatToBarPosition,
   beatsPerBar,
+  beatsPerBarAt,
   describeRejected,
   formatBarPosition,
   formatKeyName,
@@ -212,7 +232,6 @@ import {
   formatTimeSignature,
   intervalSemitones,
   isCompound,
-  isConsonantInterval,
   isStrongBeat,
   meterAt,
   metricWeight,
@@ -235,7 +254,7 @@ import {
   tryParseTimeSignature,
   tuplet,
   unwrapParse
-} from "./chunk-AGOVW7U6.js";
+} from "./chunk-YYVXRV3V.js";
 
 // src/model/interval.ts
 var INVERSION_SUM = 9;
@@ -244,6 +263,14 @@ function simpleDegree(numberValue) {
   const reduced = (numberValue - 1) % 7 + 1;
   return reduced === 1 && numberValue > 1 ? OCTAVE_DEGREES : reduced;
 }
+function checkedDirection(descending) {
+  if (typeof descending !== "boolean") {
+    throw new InvalidInputError(
+      `interval.descending must be a boolean; received ${describeRejected(descending)}`
+    );
+  }
+  return descending;
+}
 function invertQuality(quality) {
   if (quality === "P") {
     return "P";
@@ -275,6 +302,12 @@ var Interval = class _Interval {
    * @returns The interval from `a` to `b`.
    */
   static between(a, b) {
+    if (typeof a !== "object" || a === null || typeof a.intervalTo !== "function") {
+      throw new InvalidInputError(`interval a must be a Note; received ${describeRejected(a)}`);
+    }
+    if (typeof b !== "object" || b === null || typeof b.data !== "object" || b.data === null) {
+      throw new InvalidInputError(`interval b must be a Note; received ${describeRejected(b)}`);
+    }
     return a.intervalTo(b);
   }
   /**
@@ -305,7 +338,12 @@ var Interval = class _Interval {
    */
   static fromData(data) {
     const checked = toSpelledInterval(data);
-    return new _Interval(checked.number, checked.quality, checked.semitones, checked.descending);
+    return new _Interval(
+      checked.number,
+      checked.quality,
+      checked.semitones,
+      checkedDirection(checked.descending)
+    );
   }
   /**
    * Rebuild an interval from its {@link Interval.toJSON} output.
@@ -430,12 +468,15 @@ var Interval = class _Interval {
   /**
    * Whether the interval is consonant.
    *
+   * The spelling decides, not the span: a diminished fourth is a dissonance
+   * though it sounds like a major third.
+   *
    * @param twoVoice When true, the perfect fourth counts as a dissonance,
    *   matching two-voice counterpoint.
    * @returns True if the interval is consonant in that context.
    */
   isConsonant(twoVoice = true) {
-    return isConsonantInterval(this.#semitones, twoVoice);
+    return classifySpelledInterval(this.toJSON(), twoVoice) !== 2 /* Dissonance */;
   }
   /**
    * Whether another interval is spelled identically.
@@ -482,7 +523,6 @@ var Interval = class _Interval {
 };
 
 // src/model/shared.ts
-var STATED_KEY_CONFIDENCE = 1;
 function describeShape(value) {
   if (value === null) {
     return "null";
@@ -1065,6 +1105,22 @@ var Note = class _Note {
 };
 
 // src/model/timeline.ts
+var KEY_RELATIONS = [
+  "same",
+  "enharmonic",
+  "relative",
+  "parallel",
+  "dominant",
+  "subdominant",
+  "relativeOfDominant",
+  "relativeOfSubdominant"
+];
+function assertNumeral(numeral, name) {
+  if (typeof numeral !== "string") {
+    throw new InvalidInputError(`${name} must be a string; received ${describeRejected(numeral)}`);
+  }
+  return numeral;
+}
 function copySegment(segment) {
   assertDataObject(segment, "timeline segment");
   return {
@@ -1087,14 +1143,14 @@ function copyKeyRegion(region) {
     confidence: assertFiniteNumber(region.confidence, "key region confidence")
   };
   if (region.modulation !== void 0) {
-    copy.modulation = region.modulation;
+    copy.modulation = assertOneOf(region.modulation, KEY_RELATIONS, "key region modulation");
   }
   if (region.pivot !== void 0) {
     assertDataObject(region.pivot, "key region pivot");
     copy.pivot = {
       chord: new Chord(region.pivot.chord).toJSON(),
-      romanFrom: region.pivot.romanFrom,
-      romanTo: region.pivot.romanTo
+      romanFrom: assertNumeral(region.pivot.romanFrom, "key region pivot romanFrom"),
+      romanTo: assertNumeral(region.pivot.romanTo, "key region pivot romanTo")
     };
   }
   return copy;
@@ -1113,6 +1169,10 @@ function copyConfidence(confidence, segments) {
     (value, index) => assertRange(value, 0, 1, `timeline segmentConfidence[${index}]`)
   );
 }
+function validateTimeline(segments, keys) {
+  assertSpansInOrder(segments, "timeline segments");
+  assertSpansInOrder(keys, "timeline keys");
+}
 function clipSpan(span, fromBeat, toBeat) {
   const startBeat = Math.max(span.startBeat, fromBeat);
   const endBeat = Math.min(span.endBeat, toBeat);
@@ -1128,8 +1188,9 @@ var Timeline = class _Timeline {
    *
    * @param data The segments and the span they cover; copied, never retained.
    * @throws If the span, a segment, or a key region carries a number it cannot
-   *   hold — a beat that is not finite, a mode mask that names no scale — or if
-   *   the confidences do not run one per segment.
+   *   hold — a beat that is not finite, a mode mask that names no scale — if
+   *   the segments or the key regions are not disjoint, in beat order and of
+   *   positive length, or if the confidences do not run one per segment.
    */
   constructor(data) {
     assertDataObject(data, "timeline data");
@@ -1148,6 +1209,7 @@ var Timeline = class _Timeline {
     this.#segmentConfidence = Object.freeze(
       copyConfidence(data.segmentConfidence, this.#segments.length)
     );
+    validateTimeline(this.#segments, this.#keys);
   }
   /**
    * Build a timeline from placed chords.
@@ -1155,7 +1217,8 @@ var Timeline = class _Timeline {
    * @param spans The chords with their onsets, in any order.
    * @param totalBeats Where the last chord stops sounding.
    * @param key The key the chords are read in, when it is already known. It
-   *   becomes the one key region under the whole span; without it the timeline
+   *   becomes the one key region from the first chord to the end of the span;
+   *   without it, or without a chord for it to be in force over, the timeline
    *   carries no key, and the members that need one say so.
    * @returns The timeline.
    */
@@ -1163,16 +1226,9 @@ var Timeline = class _Timeline {
     const timeline = chordTimelineFromChords(spans, totalBeats);
     const data = { segments: timeline.segments, totalBeats };
     if (key !== void 0) {
-      data.keys = [
-        {
-          // The region starts where the music does, as an inferred one does,
-          // so a chord placed in a pickup is covered by the key it sounds in.
-          startBeat: timeline.segments[0]?.startBeat ?? 0,
-          endBeat: totalBeats,
-          key: keyIdentity(toKey(key)),
-          confidence: STATED_KEY_CONFIDENCE
-        }
-      ];
+      const stated = keyIdentity(toKey(key));
+      const first = timeline.segments[0];
+      data.keys = first === void 0 ? [] : statedKeyRegions(stated, first.startBeat, totalBeats);
     }
     return new _Timeline(data);
   }
@@ -1203,11 +1259,25 @@ var Timeline = class _Timeline {
    * @throws If `beatsEach` is not a positive finite number of beats.
    */
   static fromProgression(progression, beatsEach) {
+    const read = progression;
+    if (typeof read !== "object" || read === null || !Array.isArray(read.chords)) {
+      throw new InvalidInputError(
+        `timeline progression must be a Progression; received ${describeRejected(progression)}`
+      );
+    }
     assertRange(beatsEach, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "timeline beatsEach");
-    const chords = progression.chords;
-    const spans = chords.map((chord, index) => spanFromChord(chord.data, index * beatsEach));
+    const chords = read.chords;
+    const spans = chords.map((chord, index) => {
+      const data = chord?.data;
+      if (typeof data !== "object" || data === null) {
+        throw new InvalidInputError(
+          `timeline progression chords[${index}] must be a Chord; received ${describeRejected(chord)}`
+        );
+      }
+      return spanFromChord(data, index * beatsEach);
+    });
     const totalBeats = chords.length * beatsEach;
-    const key = progression.key;
+    const key = read.key;
     return key === void 0 ? _Timeline.fromChords(spans, totalBeats) : _Timeline.fromChords(spans, totalBeats, key);
   }
   /** Rebuild a timeline from the plain data {@link Timeline.data} hands out. */
@@ -1599,7 +1669,14 @@ var Progression = class _Progression {
    */
   static #attachKey(chords, key) {
     const given = assertDataObjects(chords, "progression chords");
-    return key === void 0 ? [...given] : given.map((chord) => chord.withKey(key));
+    return given.map((chord, index) => {
+      if (typeof chord.toJSON !== "function") {
+        throw new InvalidInputError(
+          `progression chords[${index}] must be a Chord; received ${describeRejected(chord)}`
+        );
+      }
+      return new Chord(chord.toJSON(), key ?? chord.key);
+    });
   }
   /**
    * Start from a chord sequence, matching the `of` factory on the other
@@ -1647,19 +1724,34 @@ var Progression = class _Progression {
     return new _Progression(chords, key);
   }
   /**
-   * Rebuild a progression from its {@link Progression.toJSON} output.
+   * Rebuild a progression from its {@link Progression.toJSON} output, with the
+   * carried key or, without one, each chord's own key.
    *
-   * @param data The serialized chords and key.
+   * @param data The serialized chords and keys.
    * @returns The progression.
+   * @throws If `chordKeys` does not hold one entry per chord.
    */
   static fromJSON(data) {
     assertDataObject(data, "progression data");
     const key = data.key === void 0 ? void 0 : Key.fromJSON(data.key);
-    const chords = assertDataArray(data.chords, "progression chords").map(
-      (chord) => Chord.fromJSON(chord)
-    );
+    const given = assertDataArray(data.chords, "progression chords");
+    const chordKeys = key === void 0 && data.chordKeys !== void 0 ? _Progression.#readChordKeys(data.chordKeys, given.length) : void 0;
+    const chords = given.map((chord, index) => {
+      const own = chordKeys?.[index];
+      return own === void 0 ? Chord.fromJSON(chord) : Chord.fromJSON(chord).withKey(own);
+    });
     return key === void 0 ? new _Progression(chords) : new _Progression(chords, key);
   }
+  /** Read the per-chord keys of {@link ProgressionData}, one entry per chord. */
+  static #readChordKeys(value, count) {
+    const entries = assertDataArray(value, "progression chord keys");
+    if (entries.length !== count) {
+      throw new InvalidInputError(
+        `progression chord keys must hold one entry per chord (${count}); received ${entries.length}`
+      );
+    }
+    return entries.map((entry) => entry === null ? void 0 : Key.fromJSON(entry));
+  }
   /**
    * Wrap plain progression data, matching the `fromData` factory on the other
    * classes.
@@ -1870,10 +1962,8 @@ var Progression = class _Progression {
    */
   voice(opts) {
     const key = opts?.key ?? this.#key;
-    return voiceProgression(
-      this.#chords.map((chord) => chord.data),
-      key === void 0 ? opts : { ...opts, key }
-    );
+    const views = opts?.key === void 0 ? this.#chords.map((chord) => chord.data) : this.#viewsIn(toKey(opts.key));
+    return voiceProgression(views, key === void 0 ? opts : { ...opts, key });
   }
   /**
    * The Roman numeral of each chord in a key.
@@ -1934,12 +2024,13 @@ var Progression = class _Progression {
     const resolved = this.#resolveKey(key);
     const chords = this.#chords.map((chord) => chord.analyze(resolved, opts));
     const { voicing, ...cadenceOpts } = opts ?? {};
-    const from = this.#chords[this.#chords.length - 2];
-    const to = this.#chords[this.#chords.length - 1];
-    const approach = this.#chords[this.#chords.length - 3];
-    const cadence = from !== void 0 && to !== void 0 ? detectCadence(from.data, to.data, resolved, {
+    const views = this.#viewsIn(resolved);
+    const from = views[views.length - 2];
+    const to = views[views.length - 1];
+    const approach = views[views.length - 3];
+    const cadence = from !== void 0 && to !== void 0 ? detectCadence(from, to, resolved, {
       ...cadenceOpts,
-      ...approach === void 0 ? {} : { approach: approach.data },
+      ...approach === void 0 ? {} : { approach },
       ...voicing === void 0 ? {} : { voicing: this.#closingVoicing(voicing) }
     }) : null;
     return { chords, cadence };
@@ -2004,17 +2095,18 @@ var Progression = class _Progression {
    */
   cadences(key, opts) {
     const resolved = this.#resolveKey(key);
+    const views = this.#viewsIn(resolved);
     const found = [];
-    for (let index = 1; index < this.#chords.length; index += 1) {
-      const from = this.#chords[index - 1];
-      const to = this.#chords[index];
+    for (let index = 1; index < views.length; index += 1) {
+      const from = views[index - 1];
+      const to = views[index];
       if (from === void 0 || to === void 0) {
         continue;
       }
-      const approach = index >= 2 ? this.#chords[index - 2]?.data : opts?.approach;
+      const approach = index >= 2 ? views[index - 2] : opts?.approach;
       const pair = opts?.voicing;
       found.push(
-        detectCadence(from.data, to.data, resolved, {
+        detectCadence(from, to, resolved, {
           ...opts?.alternatives === void 0 ? {} : { alternatives: opts.alternatives },
           ...approach === void 0 ? {} : { approach },
           ...pair === void 0 ? {} : { voicing: [pair[index - 1] ?? [], pair[index] ?? []] }
@@ -2175,16 +2267,26 @@ var Progression = class _Progression {
   /**
    * The plain progression data, for JSON serialization.
    *
-   * Private class fields do not serialize, so this preserves both the chord
-   * data and any carried key in `JSON.stringify(progression)`.
+   * Private class fields do not serialize, so this preserves the chord data,
+   * any carried key, and — for a progression with no key of its own — each
+   * chord's own key in `JSON.stringify(progression)`.
    *
-   * @returns The chord data sequence and the carried key, if any.
+   * @returns The chord data sequence, the carried key, if any, and the
+   *   per-chord keys when they are what spells the chords.
    */
   toJSON() {
-    return {
+    const out = {
       chords: this.#chords.map((chord) => chord.toJSON()),
       key: this.#key?.toJSON()
     };
+    if (this.#key === void 0 && this.#chords.some((chord) => chord.key !== void 0)) {
+      out.chordKeys = this.#chords.map((chord) => chord.key?.toJSON() ?? null);
+    }
+    return out;
+  }
+  /** The members read in `key`: spellings the caller gave, the rest derived from it. */
+  #viewsIn(key) {
+    return this.#chords.map((chord) => chord.withKey(key).data);
   }
   /**
    * Resolve the key for an analysis method: explicit first, then carried.
@@ -2617,7 +2719,8 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   roman(key, opts) {
-    return chordToRoman(this.#data, this.#resolveKey(key), opts);
+    const resolved = this.#resolveKey(key);
+    return chordToRoman(this.#dataWithKey(resolved), resolved, opts);
   }
   /**
    * The chord's Roman numeral together with the reasoning behind it: the degree
@@ -2645,7 +2748,8 @@ var Chord = class _Chord {
    * ```
    */
   explain(key, opts) {
-    return explainRoman(this.#data, this.#resolveKey(key), opts);
+    const resolved = this.#resolveKey(key);
+    return explainRoman(this.#dataWithKey(resolved), resolved, opts);
   }
   /**
    * The chord's harmonic function (tonic / subdominant / dominant) in a key.
@@ -2656,7 +2760,8 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   function(key) {
-    return functionOf(this.#data, this.#resolveKey(key));
+    const resolved = this.#resolveKey(key);
+    return functionOf(this.#dataWithKey(resolved), resolved);
   }
   /**
    * Full functional analysis: function, borrowing, Roman numeral, and the
@@ -2676,7 +2781,8 @@ var Chord = class _Chord {
    * ```
    */
   analyze(key, opts) {
-    return analyzeChord(this.#data, this.#resolveKey(key), opts);
+    const resolved = this.#resolveKey(key);
+    return analyzeChord(this.#dataWithKey(resolved), resolved, opts);
   }
   /**
    * Whether the chord is borrowed from the parallel mode (modal interchange).
@@ -2687,7 +2793,8 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   isBorrowed(key) {
-    return isBorrowedChord(this.#data, this.#resolveKey(key));
+    const resolved = this.#resolveKey(key);
+    return isBorrowedChord(this.#dataWithKey(resolved), resolved);
   }
   /**
    * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
@@ -2698,7 +2805,8 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   borrowedSource(key) {
-    return borrowedSource(this.#data, this.#resolveKey(key));
+    const resolved = this.#resolveKey(key);
+    return borrowedSource(this.#dataWithKey(resolved), resolved);
   }
   /**
    * The chord written as the figures a bass would carry under it: `6`, `64`,
@@ -2723,7 +2831,8 @@ var Chord = class _Chord {
    * ```
    */
   figuredBass(key) {
-    return figuredBassOf(this.#data, this.#resolveKey(key));
+    const resolved = this.#resolveKey(key);
+    return figuredBassOf(this.#dataWithKey(resolved), resolved);
   }
   /**
    * The chords that can stand in for this one in a key: its tritone substitute,
@@ -2750,7 +2859,8 @@ var Chord = class _Chord {
    * ```
    */
   substitutions(key, opts) {
-    return substituteChord(this.#data, this.#resolveKey(key), opts);
+    const resolved = this.#resolveKey(key);
+    return substituteChord(this.#dataWithKey(resolved), resolved, opts);
   }
   /**
    * The modal-interchange palette of the chord's key: the parallel mode's
@@ -2804,7 +2914,8 @@ var Chord = class _Chord {
    */
   voice(opts) {
     const key = opts?.key ?? this.#key;
-    return voiceChord(this.#data, key === void 0 ? opts : { ...opts, key });
+    const data = opts?.key === void 0 ? this.#data : this.#dataWithKey(toKey(opts.key));
+    return voiceChord(data, key === void 0 ? opts : { ...opts, key });
   }
   /**
    * Realize the chord as a single styled voicing (`close`, `drop2`, `drop3`,
@@ -2827,7 +2938,7 @@ var Chord = class _Chord {
    */
   negativeHarmony(key) {
     const resolved = this.#resolveKey(key);
-    return new _Chord(negativeHarmonyMirror(this.#data, resolved), resolved);
+    return new _Chord(negativeHarmonyMirror(this.#dataWithKey(resolved), resolved), resolved);
   }
   /**
    * The V7 that tonicizes this chord: a dominant seventh a perfect fifth above
@@ -3217,17 +3328,18 @@ var Key = class _Key {
         `tonic must be the class API's Note; received ${describeTonic(tonic)}; wrap plain note data with Note.fromData, or omit the tonic to have one chosen`
       );
     }
+    const note = tonic instanceof Note ? tonic : new Note(tonic.data);
     const rootPc = pitchClassOf(scale.rootPc);
-    if (tonic.pitchClass !== rootPc) {
+    if (note.pitchClass !== rootPc) {
       throw new InvalidInputError(
-        `tonic ${tonic.name} does not match the scale root pitch class ${rootPc}; pass a tonic that spells the scale root, or omit it to have one chosen`
+        `tonic ${note.name} does not match the scale root pitch class ${rootPc}; pass a tonic that spells the scale root, or omit it to have one chosen`
       );
     }
     if (variant !== void 0) {
       assertKeyVariant(variant, scale.modeMask12);
     }
     this.#scale = { rootPc, modeMask12: scale.modeMask12 };
-    this.#tonic = tonic;
+    this.#tonic = note;
     this.#variant = variant ?? variantOfMask(scale.modeMask12);
   }
   /** Preserve detection metadata while replacing its plain key with this API's Key. */
@@ -3533,7 +3645,7 @@ var Key = class _Key {
   get data() {
     return this.toJSON();
   }
-  /** The detected scale form, when this key came from key detection. */
+  /** The scale form this key stands in: natural, harmonic or melodic, read from the mask unless named. */
   get variant() {
     return this.#variant;
   }
@@ -3778,7 +3890,7 @@ var Key = class _Key {
    */
   pivotsTo(other) {
     assertKeyArgument(other, "key");
-    return pivotChords(this.#scale, other).map(({ chord, romanFrom, romanTo }) => ({
+    return pivotChords(this, resolveKey(other)).map(({ chord, romanFrom, romanTo }) => ({
       chord: new Chord(chord, this),
       romanFrom,
       romanTo
@@ -3887,7 +3999,7 @@ var Key = class _Key {
     if (this.pitchClasses().length !== HEPTATONIC_DEGREES) {
       return this.isMinor ? "minor" : "major";
     }
-    const { quality } = diatonicTriad(n, this.#scale);
+    const { quality } = diatonicTriad(n, this);
     return quality === "min" || quality === "dim" ? "minor" : "major";
   }
   /**
@@ -3896,7 +4008,7 @@ var Key = class _Key {
    *
    * Unlike {@link Key.transpose}, which picks a letter from the semitone count,
    * the interval's diatonic number decides the tonic's letter: G# minor down an
-   * augmented fourth is D minor, while down a diminished fifth it is Dbb minor.
+   * augmented fourth is D minor, while down a diminished fifth it is C## minor.
    * The mode mask is unchanged, so the scale keeps its shape.
    *
    * @param interval The interval to apply, as a name (`'A4'`, `'-A4'`), plain
@@ -4109,6 +4221,15 @@ var Key = class _Key {
     const anchor = tonic === void 0 ? this.#tonic.data : toNoteData(tonic);
     return spellPitchClasses([...pcs], anchor, this.#scale).map((note) => new Note(note));
   }
+  /**
+   * A degree chord without the spelling its builder attached.
+   *
+   * The chord carries this key, which spells its root on read, so a chord
+   * re-keyed later follows its new key instead of keeping these letters.
+   */
+  #withoutSpelling(chord) {
+    return makeChord(chord.rootPc, chord.quality);
+  }
   /**
    * Build a chord on a scale degree, carrying this key as context.
    *
@@ -4126,8 +4247,8 @@ var Key = class _Key {
    *   an explicit `quality` for those.
    */
   chord(degree, quality) {
-    const data = quality === void 0 ? diatonicTriad(degree, this.#scale) : chordFromDegree(degree, quality, this.#scale);
-    return new Chord(data, this);
+    const data = quality === void 0 ? diatonicTriad(degree, this) : chordFromDegree(degree, quality, this);
+    return new Chord(this.#withoutSpelling(data), this);
   }
   /**
    * The diatonic triad on a scale degree, carrying this key as context.
@@ -4139,7 +4260,7 @@ var Key = class _Key {
    *   degrees. Use {@link Key.chord} with an explicit quality instead.
    */
   diatonicTriad(degree) {
-    return new Chord(diatonicTriad(degree, this.#scale), this);
+    return new Chord(this.#withoutSpelling(diatonicTriad(degree, this)), this);
   }
   /**
    * The diatonic seventh chord on a scale degree, carrying this key as context.
@@ -4151,7 +4272,7 @@ var Key = class _Key {
    *   degrees. Use {@link Key.chord} with an explicit quality instead.
    */
   diatonicSeventh(degree) {
-    return new Chord(diatonicSeventh(degree, this.#scale), this);
+    return new Chord(this.#withoutSpelling(diatonicSeventh(degree, this)), this);
   }
   /**
    * Build the chord denoted by a Roman numeral in this key (including applied
@@ -4261,12 +4382,11 @@ var Key = class _Key {
    *
    * Private class fields do not serialize, so an explicit `toJSON` keeps
    * `JSON.stringify(key)` from collapsing to `{}`. The result pairs the
-   * `KeyScale` with the spelled tonic and, for a detected harmonic or melodic
-   * minor, the scale form — everything {@link Key.fromJSON} needs to rebuild a
-   * key that reads and prints as this one.
+   * `KeyScale` with the spelled tonic and the scale form — everything
+   * {@link Key.fromJSON} needs to rebuild a key that reads and prints as this
+   * one.
    *
-   * @returns The key/scale, its spelled tonic, and its scale form when it has
-   *   one.
+   * @returns The key/scale, its spelled tonic, and its scale form.
    */
   toJSON() {
     return { scale: this.scale, tonic: this.#tonic.data, variant: this.#variant };
@@ -4377,21 +4497,9 @@ function tempoFrom(tempo) {
   }
   return typeof tempo === "number" ? [{ startBeat: 0, bpm: tempo }] : tempo;
 }
-function statedKeyRegions(key, notes, totalBeats) {
+function scoreKeyRegions(key, notes, totalBeats) {
   const first = notes[0];
-  if (first === void 0 || totalBeats <= first.startBeat) {
-    return [];
-  }
-  return [
-    {
-      // The region starts where the music does, as an inferred one does, so a
-      // pickup is covered by the key it sounds in.
-      startBeat: first.startBeat,
-      endBeat: totalBeats,
-      key: keyIdentity(key),
-      confidence: STATED_KEY_CONFIDENCE
-    }
-  ];
+  return first === void 0 ? [] : statedKeyRegions(keyIdentity(key), first.startBeat, totalBeats);
 }
 function scoreData(notes, opts) {
   const data = {
@@ -4411,6 +4519,8 @@ var Score = class _Score {
   #chords;
   /** The key regions, made on the first member that needs them. */
   #regions;
+  /** The reference profile asked for with no options, made on first read. */
+  #profile;
   /**
    * Wrap plain score data.
    *
@@ -4644,43 +4754,42 @@ var Score = class _Score {
   /**
    * The notes pushed off the grid the way a player would.
    *
-   * The metric accents are read from the score's opening signature, since
-   * {@link HumanizeOptions} names one signature rather than a map; pass `ts`
-   * to read a later stretch of a score that changes meter.
+   * The metric accents are read against the score's meter map, exactly as
+   * {@link humanize} reads that map; pass `ts` to read against another meter.
    *
    * @param opts Jitter amounts, accent depth and the seed; see
    *   {@link HumanizeOptions}.
    * @returns The humanized score.
    */
   humanize(opts) {
-    return this.#withNotes(humanize(this.#data.notes, { ts: this.meterAt(0), ...opts }));
+    return this.#withNotes(humanize(this.#data.notes, { ts: this.#data.meters, ...opts }));
   }
   /**
    * The notes with ornaments added.
    *
-   * Strong positions are read from the score's opening signature, since
-   * {@link OrnamentOptions} names one signature rather than a map.
+   * Strong positions are read against the score's meter map, exactly as
+   * {@link ornament} reads that map.
    *
    * @param opts The ornament style, how much is decorated, and the seed; see
    *   {@link OrnamentOptions}.
    * @returns The ornamented score.
    */
   ornament(opts) {
-    return this.#withNotes(ornament(this.#data.notes, { ts: this.meterAt(0), ...opts }));
+    return this.#withNotes(ornament(this.#data.notes, { ts: this.#data.meters, ...opts }));
   }
   /**
    * The notes placed on a groove template's slots.
    *
-   * The template's per-bar grid is laid out against the score's opening
-   * signature, which is the signature the template must have been extracted
-   * under; a template carrying a different one is refused rather than drifting.
+   * The template's per-bar grid is laid out against the score's meter map,
+   * exactly as {@link applyGrooveTemplate} reads that map; a template extracted
+   * under another meter is refused rather than drifting.
    *
    * @param template The groove template, from `extractGrooveTemplate`.
    * @returns The score with the template's feel imposed.
    * @throws If the template was extracted under another meter.
    */
   groove(template) {
-    return this.#withNotes(applyGrooveTemplate(this.#data.notes, template, this.meterAt(0)));
+    return this.#withNotes(applyGrooveTemplate(this.#data.notes, template, this.#data.meters));
   }
   /**
    * The feel of the score's own timing, as a template another score can take on.
@@ -4689,8 +4798,8 @@ var Score = class _Score {
    * slot by slot for how far ahead of or behind the grid it sits and how hard
    * it is struck, and the reading is handed back as a template. Only the
    * subdivision is named, because the score already holds the meter the grid is
-   * laid out against — its opening signature, which is the one the template
-   * records and the one an apply-time meter is checked against.
+   * laid out against — its meter map, read exactly as
+   * {@link extractGrooveTemplate} reads that map.
    *
    * @param subdivision Grid steps per quarter-note beat; a sixteenth-note grid
    *   by default, which is where swing, push and drag are audible.
@@ -4704,7 +4813,7 @@ var Score = class _Score {
    * ```
    */
   grooveTemplate(subdivision) {
-    return extractGrooveTemplate(this.#data.notes, this.meterAt(0), subdivision);
+    return extractGrooveTemplate(this.#data.notes, this.#data.meters, subdivision);
   }
   /**
    * The harmony the notes spell out, in time.
@@ -4758,7 +4867,8 @@ var Score = class _Score {
   keys(opts) {
     if (opts !== void 0) {
       if (this.#key !== void 0) {
-        return statedKeyRegions(this.#key, this.#data.notes, opts.totalBeats ?? this.totalBeats);
+        const totalBeats = opts.totalBeats === void 0 || opts.totalBeats === null ? this.totalBeats : assertRange(opts.totalBeats, 0, Number.MAX_SAFE_INTEGER, "key timeline totalBeats");
+        return scoreKeyRegions(this.#key, this.#data.notes, totalBeats);
       }
       return keyTimelineFromNotes(this.#data.notes, { meters: this.#data.meters, ...opts });
     }
@@ -4842,10 +4952,16 @@ var Score = class _Score {
    * @returns The grouping, its downbeats, a confidence, and a rationale.
    */
   hypermeter(opts) {
-    return hypermeter(this.#data.notes, this.#data.meters, {
-      cadenceBeats: this.#cadenceBeats(),
-      ...opts
-    });
+    const asked = { ...opts };
+    if ((asked.cadenceBeats ?? null) !== null) {
+      return hypermeter(this.#data.notes, this.#data.meters, asked);
+    }
+    return hypermeterOver(
+      this.#data.notes,
+      this.#data.meters,
+      asked,
+      () => this.#cadenceSpans(asked.budget)
+    );
   }
   /**
    * The motifs the melody repeats.
@@ -4860,8 +4976,9 @@ var Score = class _Score {
    *
    * A melody is one line, so a score holding several is read as its top voice:
    * notes struck together are one event and the highest of them stands for it.
-   * A piano part read whole therefore answers for the voice a listener follows
-   * rather than for a line assembled from the insides of its chords. Split the
+   * A block-chord part read whole therefore answers for its top voice rather
+   * than for a line assembled from the insides of its chords; a lower note
+   * struck while a higher one still sounds stays in the line, though. Split the
    * score into lines first to have each of them answered for.
    *
    * @param opts Cell-length bounds and the recurrence threshold; see
@@ -4898,6 +5015,143 @@ var Score = class _Score {
   contour() {
     return melodicContour(this.#data.notes);
   }
+  /**
+   * The score's structural fingerprint: form, phrase shape, harmonic function
+   * and rhythm, and how its motifs derive from one another.
+   *
+   * The harmony is the score's own kept chord analysis, read once whether this
+   * is asked before or after {@link Score.timeline} — unless `opts.timeline`
+   * gives the harmony directly, in which case the reading runs fresh through
+   * {@link analyzeReference} rather than the harmony this score already holds.
+   * The meter, the key and the span are the score's own and are not on offer
+   * here: a caller wanting another meter reads through {@link
+   * Score.withMeters}, and one wanting another key or span calls {@link
+   * analyzeReference} directly.
+   *
+   * Asked with no options, the answer is kept and a copy of it handed back, as
+   * {@link Score.timeline} keeps its own reading; asked with options, the
+   * answer is read afresh and not kept.
+   *
+   * @param opts The harmony, the melody, and the budget; see {@link
+   *   ReferenceProfileOptions}. Meter, key and span are the score's own.
+   * @returns The profile.
+   * @example
+   * ```ts
+   * import { Score } from '@libraz/libcantus';
+   * const triad = (pitches: number[], startBeat: number) =>
+   *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
+   * const score = Score.of(
+   *   [
+   *     ...triad([60, 64, 67], 0),
+   *     ...triad([65, 69, 72], 4),
+   *     ...triad([67, 71, 74], 8),
+   *     ...triad([60, 64, 67], 12),
+   *   ],
+   *   { key: 'C major' },
+   * );
+   * score.reference().harmony.chords.map((chord) => chord.roman); // ['I', 'IV', 'V', 'I']
+   * ```
+   */
+  reference(opts) {
+    if (opts === void 0 && this.#profile !== void 0) {
+      return copyPlain(this.#profile, "reference profile");
+    }
+    const keyed = this.#key === void 0 ? {} : { key: keyIdentity(this.#key) };
+    const asked = {
+      meters: this.#data.meters,
+      totalBeats: this.totalBeats,
+      ...keyed,
+      ...opts
+    };
+    const profile = opts?.timeline === void 0 ? referenceFromReadings(this.#data.notes, this.#chordAnalysis(), asked) : analyzeReference(this.#data.notes, asked);
+    if (opts === void 0) {
+      this.#profile = profile;
+      return copyPlain(profile, "reference profile");
+    }
+    return profile;
+  }
+  /**
+   * The onset placement of the score's melodic line.
+   *
+   * A melody is one line, so a score holding several is read as its top voice,
+   * as {@link Score.motifs} and {@link Score.contour} are.
+   *
+   * @param opts The span's end and the budget; see {@link
+   *   RhythmAnalysisOptions}. The meter is the score's own.
+   * @returns The rhythm reading.
+   * @example
+   * ```ts
+   * import { Score } from '@libraz/libcantus';
+   * const score = Score.of([
+   *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+   *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+   *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+   *   { pitch: 65, startBeat: 3, durationBeat: 1 },
+   * ]);
+   * score.rhythm().onsetDensity; // 4
+   * ```
+   */
+  rhythm(opts) {
+    return analyzeRhythm(this.#data.notes, {
+      meters: this.#data.meters,
+      totalBeats: this.totalBeats,
+      ...opts
+    });
+  }
+  /**
+   * How the score's motifs derive from one another: which statement grew out
+   * of which, and by what transformation.
+   *
+   * {@link Score.motifs} finds the cells; this reads across their occurrences
+   * and names, for every statement after the first, the earlier one it most
+   * plausibly grew out of. A melody is one line, so a score holding several is
+   * read as its top voice, as {@link Score.motifs} is.
+   *
+   * @param opts Cell-length bounds and the recurrence threshold {@link
+   *   Score.motifs} takes, plus the variation threshold and the budget; see
+   *   {@link MotifGraphOptions} and {@link ExtractMotifsOptions}.
+   * @returns The derivation forest.
+   * @example
+   * ```ts
+   * import { Score } from '@libraz/libcantus';
+   * const score = Score.of([
+   *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+   *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+   *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+   *   { pitch: 60, startBeat: 3, durationBeat: 1 },
+   *   { pitch: 62, startBeat: 4, durationBeat: 1 },
+   *   { pitch: 64, startBeat: 5, durationBeat: 1 },
+   * ]);
+   * score.motifGraph().edges.length; // 1
+   * ```
+   */
+  motifGraph(opts) {
+    return motifGraph(this.#data.notes, extractMotifs(this.#data.notes, opts), {
+      key: this.key(),
+      ...opts
+    });
+  }
+  /**
+   * How this score, read as a melody, keeps to a composition plan.
+   *
+   * @param plan The plan the melody was written for.
+   * @param opts The budget; see {@link EvaluateCompositionOptions}.
+   * @returns The violations found and the fit reading; see {@link
+   *   evaluateComposition}.
+   * @example
+   * ```ts
+   * import { Composer, Score } from '@libraz/libcantus';
+   * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+   *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+   * );
+   * const composer = Composer.of({ key: 'C major', seed: 5 });
+   * const plan = composer.plan(Score.of(notes, { key: 'C major' }).reference());
+   * composer.melody(plan).evaluate(plan).violations.some((v) => v.severity === 'error'); // false
+   * ```
+   */
+  evaluate(plan, opts) {
+    return evaluateComposition(this.#data.notes, plan, opts);
+  }
   /**
    * Each note's role in the harmony sounding under it.
    *
@@ -5125,15 +5379,24 @@ var Score = class _Score {
    * Kept on first reading for the same reason the chord timeline is.
    */
   #keyRegions() {
-    const regions = this.#regions ?? (this.#key === void 0 ? keyTimelineFromNotes(this.#data.notes, { meters: this.#data.meters }) : statedKeyRegions(this.#key, this.#data.notes, this.totalBeats));
+    const regions = this.#regions ?? (this.#key === void 0 ? keyTimelineFromNotes(this.#data.notes, { meters: this.#data.meters }) : scoreKeyRegions(this.#key, this.#data.notes, this.totalBeats));
     this.#regions = regions;
     return regions;
   }
-  /** Where the score's own harmony closes, as beats. */
-  #cadenceBeats() {
-    return detectCadences(this.#chordTimeline(), this.#keyContext(void 0)).map(
-      (hit) => hit.atBeat
+  /**
+   * Where the score's own harmony closes, as the spans its arrival chords sound
+   * through, read in the key {@link Score.phrases} reads them in.
+   */
+  #cadenceSpans(budget) {
+    const timeline = this.#chordTimeline();
+    const key = keyContextFor(
+      this.#key === void 0 ? void 0 : keyIdentity(this.#key),
+      timeline,
+      this.#data.meters,
+      void 0,
+      budget
     );
+    return boundaryCadences(timeline, key).spans;
   }
   /** The score's context as chord-timeline options, with the caller's on top. */
   #analysisOptions(opts) {
@@ -5209,7 +5472,7 @@ function copySegments(segments) {
 function chordTimelineOf(segments) {
   return new Timeline({ segments: [...segments], totalBeats: spanEnd(segments) }).chordTimeline;
 }
-function copySettings(settings, trackCount) {
+function copySettings(settings, tracks) {
   if (settings === void 0) {
     return void 0;
   }
@@ -5236,8 +5499,9 @@ function copySettings(settings, trackCount) {
       settings.harmonyTracks,
       "arrangement harmonyTracks"
     ).map(
-      (track, index) => assertInteger(track, `arrangement harmonyTracks[${index}]`, 0, trackCount - 1)
+      (track, index) => assertInteger(track, `arrangement harmonyTracks[${index}]`, 0, tracks.length - 1)
     );
+    harmonyTrackSet(copy.harmonyTracks, tracks, "arrangement harmonyTracks");
   }
   if (settings.minSeverity !== void 0) {
     copy.minSeverity = assertInteger(
@@ -5254,6 +5518,11 @@ function copySettings(settings, trackCount) {
       Number.MAX_SAFE_INTEGER,
       "arrangement pickupBeats"
     );
+    assertTrackNotes(tracks, {
+      allowNonPositiveDuration: true,
+      minStartBeat: -copy.pickupBeats,
+      budget: settings.budget
+    });
   }
   if (settings.harmonicRhythm !== void 0) {
     copy.harmonicRhythm = assertRange(
@@ -5264,7 +5533,7 @@ function copySettings(settings, trackCount) {
     );
   }
   if (settings.profile !== void 0) {
-    copy.profile = settings.profile;
+    copy.profile = arrangementProfile(settings.profile);
   }
   if (settings.budget !== void 0) {
     copy.budget = assertPositiveInt(settings.budget, "arrangement budget", Number.MAX_SAFE_INTEGER);
@@ -5277,7 +5546,7 @@ function copyArrangement(data) {
   const tracks = assertDataArray(data.tracks, "arrangement tracks").map(
     (track, index) => copyTrack(track, index, budget)
   );
-  const settings = copySettings(data.settings, tracks.length);
+  const settings = copySettings(data.settings, tracks);
   return settings === void 0 ? { tracks } : { tracks, settings };
 }
 function arrangementData(tracks, settings) {
@@ -5532,6 +5801,71 @@ var Arrangement = class _Arrangement {
       keys: [...keys]
     });
   }
+  /**
+   * The arrangement's structural fingerprint: form, phrase shape, harmonic
+   * function and rhythm, and how its melody's motifs derive from one another.
+   *
+   * The harmony reads the arrangement's own session analysis directly — the
+   * tracks `settings.harmonyTracks` names, or else every track but the
+   * percussion ones — so the harmony is never inferred a second time. The
+   * melody is the notes of the tracks played with `role: 'melody'`, joined in
+   * the order the tracks were given; an arrangement naming none reads the top
+   * line of the harmony notes instead, as {@link analyzeReference} does
+   * without a `melody` option. Meter, key, harmony and melody are the
+   * arrangement's own and are not on offer here: a caller wanting others calls
+   * {@link analyzeReference} directly, with the same notes {@link
+   * Arrangement.tracks} hands out.
+   *
+   * @param opts The budget; see {@link ReferenceProfileOptions}.
+   * @returns The profile.
+   * @example
+   * ```ts
+   * import { Arrangement } from '@libraz/libcantus';
+   * const triad = (pitches: number[], startBeat: number) =>
+   *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
+   * const arrangement = Arrangement.of(
+   *   [
+   *     {
+   *       name: 'lead',
+   *       role: 'melody',
+   *       notes: [
+   *         ...triad([60, 64, 67], 0),
+   *         ...triad([65, 69, 72], 4),
+   *         ...triad([67, 71, 74], 8),
+   *         ...triad([60, 64, 67], 12),
+   *       ],
+   *     },
+   *   ],
+   *   { key: 'C major' },
+   * );
+   * arrangement.reference().harmony.chords.map((chord) => chord.roman); // ['I', 'IV', 'V', 'I']
+   * ```
+   */
+  reference(opts) {
+    const tracks = this.#data.tracks;
+    const harmonyTracks = this.#data.settings?.harmonyTracks;
+    const harmony = [];
+    const melody = [];
+    for (let index = 0; index < tracks.length; index += 1) {
+      const track = tracks[index];
+      if (track === void 0) {
+        continue;
+      }
+      if (track.role !== "drums" && (harmonyTracks === void 0 || harmonyTracks.includes(index))) {
+        harmony.push(...track.notes);
+      }
+      if (track.role === "melody") {
+        melody.push(...track.notes);
+      }
+    }
+    return referenceFromReadings(harmony, this.#session().analysis, {
+      // The meter the arrangement's own analysis reads, `ts` included.
+      meters: this.#data.settings?.meters ?? this.#data.settings?.ts,
+      totalBeats: this.timeline().totalBeats,
+      ...melody.length === 0 ? {} : { melody },
+      ...opts
+    });
+  }
   /**
    * Whether another arrangement holds the same tracks under the same settings.
    *
@@ -5637,7 +5971,9 @@ function copyProfile(profile) {
   }
   const reach = {};
   for (const [pitch, limbs] of Object.entries(profile.reach)) {
-    reach[Number(pitch)] = [...limbs];
+    if (String(Number(pitch)) === pitch) {
+      reach[Number(pitch)] = [...limbs];
+    }
   }
   const percussion = {
     kind: "percussion",
@@ -6149,7 +6485,7 @@ var Composer = class _Composer {
       ...instrument === void 0 ? {} : { instrument: toStringedProfile(instrument, "bass instrument") },
       segments,
       key,
-      ts: this.#openingMeter(),
+      ts: this.#meters,
       ctx: this.context
     });
     return Score.of(notes, this.#scoreOptions(key));
@@ -6181,7 +6517,7 @@ var Composer = class _Composer {
       ...timeline === void 0 ? {} : { timeline: toChordTimeline(timeline) },
       melody: melody.notes,
       key,
-      ts: this.#openingMeter(),
+      ts: this.#meters,
       ctx: this.context
     });
     return Score.of(notes, this.#scoreOptions(key));
@@ -6211,14 +6547,15 @@ var Composer = class _Composer {
       ...opts,
       melody: melody.notes,
       ...this.#key === void 0 ? {} : { key: this.#key },
-      ts: this.#openingMeter(),
+      ts: this.#meters,
       ctx: this.context
     });
     const moved = melody.transpose(result.transposeSemitones);
+    const last = result.chords[result.chords.length - 1];
     const totalBeats = harmonizedSpan(
       moved.totalBeats,
       result.chords,
-      beatsPerBar(this.#openingMeter())
+      beatsPerBarAt(last?.startBeat ?? 0, this.#meters)
     );
     return {
       chords: Timeline.fromChords(result.chords, totalBeats, result.key),
@@ -6228,6 +6565,73 @@ var Composer = class _Composer {
       transposeSemitones: result.transposeSemitones
     };
   }
+  /**
+   * A composition plan derived from a reference profile.
+   *
+   * The composer's key is the plan's home key unless `opts.key` names another,
+   * and its seed and algorithm version are the ones the plan records, so the
+   * plan is written under the same recipe as the composer's other parts.
+   *
+   * @param reference The reference profile to derive from.
+   * @param opts Everything {@link deriveCompositionPlan} takes but the context,
+   *   which is the composer's.
+   * @returns The plan.
+   * @throws If the composer draws from a caller-held `rng`: a plan records its
+   *   seed, and a source cannot be written into it.
+   * @example
+   * ```ts
+   * import { Composer, Score } from '@libraz/libcantus';
+   * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+   *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+   * );
+   * const reference = Score.of(notes, { key: 'C major' }).reference();
+   * const plan = Composer.of({ key: 'D major', seed: 5 }).plan(reference);
+   * plan.seed; // 5
+   * plan.keys[0].scale.rootPc; // 2
+   * ```
+   */
+  plan(reference, opts) {
+    const ctx = this.context;
+    if (ctx.rng !== void 0) {
+      throw new InvalidInputError(
+        "composer plan cannot record a caller-held rng; give the composer a seed instead"
+      );
+    }
+    return deriveCompositionPlan(reference, {
+      ...this.#key === void 0 ? {} : { key: this.#key },
+      ...opts,
+      ctx
+    });
+  }
+  /**
+   * A melody written to a composition plan.
+   *
+   * The plan is the reproduction recipe, so its seed and algorithm version are
+   * the ones the melody is drawn under, not the composer's. The score is read
+   * in the plan's meter and home key, at the composer's tempo.
+   *
+   * @param plan The plan to follow.
+   * @param opts The budget; see {@link MelodyOptions}.
+   * @returns The melody, as a score.
+   * @example
+   * ```ts
+   * import { Composer, Score } from '@libraz/libcantus';
+   * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+   *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+   * );
+   * const composer = Composer.of({ key: 'C major', seed: 5 });
+   * const plan = composer.plan(Score.of(notes, { key: 'C major' }).reference());
+   * composer.melody(plan).notes.length > 0; // true
+   * ```
+   */
+  melody(plan, opts) {
+    const notes = generateMelody(plan, opts);
+    const score = { meters: plan.meters, key: plan.keys[0] };
+    if (this.#options.bpm !== void 0) {
+      score.tempo = this.#options.bpm;
+    }
+    return Score.of(notes, score);
+  }
   /**
    * Whether another composer holds the same settings.
    *
@@ -6286,16 +6690,6 @@ var Composer = class _Composer {
     }
     return this.#key;
   }
-  /**
-   * The signature the parts are written against.
-   *
-   * Each generator names one time signature rather than a map, so a composer
-   * whose meter changes hands over the signature its music opens on — the same
-   * reading {@link Score.humanize} and its siblings take.
-   */
-  #openingMeter() {
-    return meterAt(0, this.#meters);
-  }
   /**
    * The one signature a part laid out in bars is written against.
    *
@@ -6310,7 +6704,7 @@ var Composer = class _Composer {
         `composer ${part} needs one meter for the whole part; the composer changes meter`
       );
     }
-    return this.#openingMeter();
+    return meterAt(0, this.#meters);
   }
   /** The context every score a composer hands back is read against. */
   #scoreOptions(key) {
@@ -6807,6 +7201,7 @@ var Motif = class _Motif {
    * ```
    */
   static generate(opts) {
+    assertRecord(opts, "motif options");
     return new _Motif(generateMotif({ ...opts, chord: chordFrom(opts.chord) }));
   }
   /**
@@ -6821,7 +7216,7 @@ var Motif = class _Motif {
    * @throws If a note carries a value the transforms cannot hold.
    */
   static fromNotes(notes) {
-    return new _Motif({ notes: [...notes] });
+    return new _Motif({ notes: [...assertArray(notes, "motif notes")] });
   }
   /** Rebuild a motif from the plain data {@link Motif.data} hands out. */
   static fromData(cell) {
@@ -7140,7 +7535,7 @@ var Rhythm = class _Rhythm {
    * @returns The compressed pattern.
    */
   doubleTime() {
-    return this.#withGrid(doubleTime(toGrid(this.#data.events), this.#spanSteps()));
+    return this.#withGrid(doubleTimeFigure(toGrid(this.#data.events), this.#spanSteps()));
   }
   /**
    * Stretch the pattern to twice its length: everything falls half as often.
@@ -7151,7 +7546,7 @@ var Rhythm = class _Rhythm {
    * @returns The stretched pattern.
    */
   halfTime() {
-    return this.#withGrid(halfTime(toGrid(this.#data.events), this.#spanSteps()));
+    return this.#withGrid(halfTimeFigure(toGrid(this.#data.events), this.#spanSteps()));
   }
   /**
    * Keep as much decoration as the ornament dial asks for.
@@ -7198,14 +7593,16 @@ var Rhythm = class _Rhythm {
       rhythmic: resolved.rhythmic,
       ornament: resolved.ornament,
       rate: opts?.rate,
-      spanSteps: this.#spanSteps(),
       ts: this.#data.ts,
       // The transform hands the predicate the events it was given, which carry
       // the onset each was built from; the parameter is declared over the bare
       // grid event the rule reads, so the field is named back here.
       isOrnament: isOrnament === void 0 ? void 0 : (grid) => isOrnament(grid.source)
     };
-    return this.#withGrid(deform(toGrid(this.#data.events), options, resolved.part(PART)));
+    const dials = resolveDials(options);
+    return this.#withGrid(
+      deformFigure(toGrid(this.#data.events), this.#spanSteps(), dials, resolved.part(PART), [])
+    );
   }
   /**
    * Whether one player can sustain the pattern at the context's tempo.
@@ -7266,7 +7663,11 @@ var Rhythm = class _Rhythm {
   toJSON() {
     return this.data;
   }
-  /** The pattern's span as a count of sixteenths, for the transforms. */
+  /**
+   * The pattern's span as a count of sixteenths, for the transforms: whatever
+   * span the pattern covers, an empty one or one ending off the straight grid
+   * included.
+   */
   #spanSteps() {
     return spanOf(this.#data.events) / STEP_BEATS;
   }
@@ -8250,4 +8651,4 @@ export {
   Tuning,
   Voicing
 };
-//# sourceMappingURL=chunk-FBH75DAY.js.map
+//# sourceMappingURL=chunk-5MWRBYAT.js.map